Search tools, AI agents, MCP servers
Submit a tool

Search iThub

Search tools, categories and collections. Type at least two characters.

Explore all tools
↑ ↓ to explore resultsEnter to open · Esc to close

Mercury Agent

Open-source personal AI agent with permission checks, local SQLite memory, token budgets and chat channels

AI Assistants & ChatOpen sourcev1.5.4

Mercury Agent at a glance

Pricing
Open source
Deployment
Self-hosted
License
Open source
Version
v1.5.4November 17, 2026
Platforms
WindowsmacOSLinux
Language
TypeScript
Data location
Runs on the user's computer or server; memory, configuration and keys stay in ~/.mercury. Prompts go to the configured model provider; optional Mercury Cloud is a hosted backend (region not stated).
Maker
cosmicstack-labs
Founded
2026

What is Mercury Agent?

Mercury Agent is an open-source AI agent developed by Cosmic Stack in the cosmicstack-labs/mercury-agent repository. It runs as one background process on the user's computer or server and can be reached from a terminal interface, the Mercury Desktop app, a local web dashboard, Telegram, Discord, Slack and Signal, all sharing the same memory and permission rules. The agent reads and writes files, runs shell commands, works with git and GitHub, fetches web pages and keeps schedules, and every action is checked against user-defined rules and a daily token budget. Its character is defined by editable Markdown files such as soul.md, persona.md, taste.md and heartbeat.md.

There are three ways to install it. The one-line installers for macOS, Linux and Windows download a standalone binary for the operating system and CPU and verify its checksum, so Node.js is not needed. The npm package @cosmicstack/mercury-agent requires Node.js 22 or newer. Mercury Desktop is a separate app for macOS 11 or newer (Apple Silicon and Intel), Windows 10 and 11 (x64, as .exe or .msi) and Linux x64 (AppImage, .deb and .rpm) that installs the runtime locally or connects to Mercury on another machine; the desktop builds are not code-signed yet. The documentation also covers Android through Termux. The runtime registers itself as a LaunchAgent on macOS, a systemd service on Linux or a Task Scheduler task on Windows and restarts after a crash.

The latest GitHub release is Mercury Agent v1.5.4, published on November 17, 2026. It lets paired phones set voice provider keys and limits approval prompts from other devices to plugin installs. Version 1.5.3 added a Google Workspace connection through Google's gws tool, stricter rules that keep bots from acting on instructions found in files or pages they read, and server support for native iPhone and Android apps that are in the repository but not yet in the app stores. Mercury Desktop first shipped with version 1.5.0 on November 3, 2026. The changelog lists every release.

Mercury is written in TypeScript. Long-term memory, called the Second Brain, is stored in a SQLite database with full-text search under ~/.mercury, and all configuration, keys, sessions, skills and bot data live in that folder rather than in the user's projects. The web dashboard is a React application bound to 127.0.0.1:6174. Mercury acts as a client for MCP servers over stdio and Streamable HTTP, and installs community skills that follow the Agent Skills specification from skills.mercuryagent.sh. Supported model providers include DeepSeek, OpenAI, Anthropic, Grok, Ollama (cloud and local), LM Studio, several hosted inference services, any OpenAI-compatible endpoint and Mercury Cloud, with automatic fallback between them.

The project is MIT-licensed and the website states that the agent itself has no telemetry. Mercury Cloud is an optional hosted backend that pairs with a local install through mercury cloud connect, keeps a WebSocket connection open, offers Mercury Flash and Mercury Pro models and adds a remote dashboard at cloud.mercuryagent.sh. Vulnerabilities are reported through the repository's security policy. Similar self-hosted agents on iThub include OpenClaw, Hermes Agent and ZeroClaw.

Key capabilities

  • One-line installers curl -fsSL https://mercuryagent.sh/install.sh | sh on macOS and Linux and irm https://mercuryagent.sh/install.ps1 | iex in Windows PowerShell download a standalone binary and verify its checksum. Release assets include binaries for macOS arm64 and x64, Linux x64 and arm64 and Windows x64, with baseline builds for CPUs without AVX2. mercury upgrade updates an existing install.
  • npm package npm i -g @cosmicstack/mercury-agent installs the same agent on Node.js 22 or newer. This is also the documented path for Android, where Mercury runs inside Termux installed from F-Droid or GitHub, with about 500 MB of free storage.
  • Mercury Desktop A Tauri desktop app for macOS, Windows and Linux that can install Mercury on the current computer or connect to Mercury on a server, a home machine or Mercury Cloud, with several connections in one window. Remote connections are approved on the target machine with a short code and stored in the operating system keychain. Builds are not code-signed yet, so macOS and Windows ask for confirmation on first launch, and updates are checked against Mercury's update signature.
  • Always-on runtime A single background process owns the channels, bots, scheduler and web dashboard and is installed as a login service on each operating system. Running mercury attaches the terminal to that process, so closing the terminal does not stop running tasks. mercury status, mercury logs and mercury doctor manage it.
  • Chat channels Telegram supports admins, members, pairing codes, streaming replies, file delivery and inline approval buttons. Discord adds slash commands with admin roles and guild and channel scoping, Slack uses Socket Mode with no public endpoint, and Signal runs end-to-end encrypted through signal-cli. Notifications go to the first configured channel in a fixed order.
  • Local web dashboard A React dashboard at http://127.0.0.1:6174 offers chat, a bots cockpit, a memory explorer, Kanban boards, providers, skills, permissions, schedules and usage. It is disabled by default, bound to localhost and protected by a password generated on first run.
  • Permission system Shell commands pass through a blocklist that cannot be overridden, covering sudo and variants of rm -rf /, and anything outside the allowed scopes needs approval. File access is scoped per folder, channel and role, fetch_url blocks private address ranges and caps response sizes, and secrets are redacted from logs. Each session runs in Ask Me or Allow All mode.
  • Second Brain memory After each conversation Mercury extracts up to three facts in ten types, including preferences, goals, projects, decisions and constraints, with confidence, importance and durability scores. Relevant memories are recalled before each answer within a fixed budget, consolidated hourly, and aged out when stale. The SQLite database can be inspected or cleared with /memory or disabled in the configuration.
  • Token budget and Token Saver A daily token budget is enforced on every turn, and /budget shows current usage. When usage rises, Token Saver mode trims context and can route routine work to a cheaper model. Mercury Bots have their own daily budgets per bot and per fleet.
  • Mercury Code mercury code [dir] opens a full-screen coding environment in a repository. AUTO mode plans and builds in one pass and asks once before large changes, a live checklist shows each step, and a task is reported as done only after a build, test or typecheck has run and passed. /ws browses, stages, commits and undoes changes.
  • Mercury Bots Persistent specialist agents with their own persona, model, memory, permission tier and daily budget run beside the main agent. A lead bot can delegate tasks to a crew and run pipelines defined in bot.yaml, and finished files land in ~/Documents/Mercury/<Bot name>/ or arrive as Telegram attachments. Bots fail closed when a permission is missing.
  • About 50 built-in tools Tools cover files, shell, git, GitHub pull requests and issues (with a GITHUB_TOKEN), web fetching, skills, scheduling, memory, saved sessions, sub-agents, user interaction and Spotify playback. In-chat commands such as /status, /models and /permissions run locally without using tokens.
  • MCP client mercury mcp add registers local stdio servers or remote Streamable HTTP servers with static headers. A server's tools stay hidden until they are allowed by name, every call asks in Ask Me mode, and Allow All does not cover MCP tools. Resource templates, prompts, sampling, OAuth sign-in and legacy SSE servers are not supported yet, and bots do not receive MCP tools.
  • Skills mercury skills search, view and install work with the community registry at skills.mercuryagent.sh, based on the Agent Skills specification. The README notes that community skills are not audited. Skills can also be installed from the web dashboard or, by admins, from Telegram.
  • Model providers with fallback Mercury tries the default provider first and falls back to the others on failure, skipping providers whose key was rejected. Supported options include Mercury Cloud, DeepSeek, OpenAI, Anthropic, Grok, Atlas Cloud, Runcrate, CloudGPU, AI/ML API, MiMo, Ollama Cloud and Local, LM Studio, LiteLLM, GitHub Copilot endpoints and any OpenAI-compatible URL, including servers behind basic authentication.
  • Scheduler and Kanban boards schedule_task creates cron schedules and one-shot delays whose results return to the channel that created them. Kanban boards are worked through card by card in dependency order, with token usage tracked per card.
  • Google Workspace and isolated browser reader mercury google connect links Gmail, Drive and Docs through Google's gws tool, read-only by default, with sends, shares, uploads and deletes always asking first. An optional browser reader renders public pages in an installed browser with a temporary profile per chat; page actions and JavaScript are disabled and no browser engine is bundled.

Where Mercury Agent fits

Personal assistant across chat apps

After the setup wizard, the same agent answers in the terminal, the desktop app and any configured Telegram, Discord, Slack or Signal chat. Memories extracted in one channel are available in the others, and approval requests appear as buttons in Telegram or as cards in Mercury Desktop. Shared Telegram or Discord channels have admin and member roles, and members cannot widen their own access.

Coding inside a repository

Mercury Code works in a project folder with git status, diffs, commits, pushes and GitHub pull requests and issues. The project describes its completion rule as verified: a task ends as done only when a build, test or typecheck ran and passed, otherwise Mercury names the blocker. Longer tasks can be handed to a sub-agent with /code agent while the session continues.

Scheduled research and writing with bots

Mercury Bots are created with /bots create and run on their own schedules with separate budgets and permissions. A fleet can split work between bots and return one summary, and deliverables are written to a folder per bot or sent to Telegram. The /bots roster offers Stop, Start and Run controls from Telegram.

Running Mercury on a server and connecting from a laptop

The command-line runtime runs on a VPS, a home server or a Raspberry Pi, and Mercury Desktop connects to it as a remote connection. The desktop app requests a device token that the owner approves on the server side, through a code sent to Telegram or WhatsApp or shown in /server, and the token can be revoked from either side. Mercury Cloud is an alternative that keeps a local agent reachable without port forwarding.

Extending the agent with MCP servers and skills

Issue trackers, databases and internal tools that ship as MCP servers are added with mercury mcp add, after which individual tools are allowed by name. Secrets for these servers are kept in ~/.mercury/.env and referenced from the configuration. Community skills are installed from the Mercury skills registry after reading them with mercury skills view.

Working with local models

Ollama Local and LM Studio providers point Mercury at models running on the same machine or network, and the OpenAI-compatible provider covers other self-hosted endpoints. Combined with the local SQLite memory and the localhost dashboard, this setup keeps prompts, memory and configuration on hardware the user controls; cloud providers are used only when they are configured.

Install

curl -fsSL https://mercuryagent.sh/install.sh | sh

Reviews of Mercury Agent

No reviews yet

Be the first to share your experience with Mercury Agent.

Loading review form…

Found Mercury Agent useful? Upvote it todayYour vote helps other IT teams find it in the daily ranking.

Similar to Mercury Agent

Compare:Mercury Agent vs OpenClawMercury Agent vs Hermes AgentMercury Agent vs ZeroClaw

  1. OpenClawSelf-hosted AI assistant Gateway that answers in your chat apps and runs tools on your own devicesAI Assistants & Chat7 views
  2. Hermes AgentSelf-hosted AI agent by Nous Research with persistent memory, self-written skills, cron jobs and chat gatewaysAgent Frameworks10 views
  3. ZeroClawSelf-hosted AI agent runtime in one Rust binary, with 30+ chat channels, approval gates and OS sandboxingAgent Frameworks3 views
  4. AnythingLLMMIT-licensed AI app for document chat, agents and local or hosted LLMs, on desktop, Docker or cloudAI Assistants & Chat47 views
  5. GPT4AllFree MIT-licensed desktop app by Nomic AI for running open LLMs locally, with LocalDocs and a local APIAI Assistants & Chat47 views
  6. Cherry StudioDesktop AI workspace for cloud and local models, agents, MCP tools and local knowledge basesAI Assistants & Chat18 views
  7. SuparagentOpen-source workspace for named AI agents with teams, memory, routines and approval controlsAI Assistants & Chat16 views
  8. 5ireDesktop AI assistant and MCP client with tool approvals, local document retrieval and multi-provider chatAI Assistants & Chat13 views