MCP Server

Atuin ships with a built-in MCP (Model Context Protocol) server, giving AI agents like Claude Code, Codex, Hermes Agent, Kiro CLI, opencode, pi and Cursor access to your shell history. Your agent can look up commands you've run before, check whether they succeeded, and — with output capture set up — read what they printed, or search that output for something it remembers seeing.

The server exposes the same history tools that Atuin AI uses, plus output search and search over your agent threads. All tools are read-only: nothing can modify or delete your history, and all data stays on your machine.

Quick start

Connect all your configured agents with one command:

atuin mcp install

Atuin checks for existing user config files for Claude Code, Codex, Grok Build (grok), Hermes Agent (hermes), Kiro CLI, opencode, pi and oh-my-pi (omp), lists the agents it found and asks once before registering the MCP server with all of them. Agents without a config file are skipped. You can also target one directly with atuin mcp install claude-code (or codex, grok, hermes, kiro, opencode, pi, omp), including when its config file doesn't exist yet.

Then restart the agents you connected. They can now search your shell history.

To let it read and search what your commands printed, and your past threads with other agents, turn those on too (each also sets up the daemon they need):

atuin config enable output-capture
atuin config enable threads

To check it worked, ask the agent "What's the last command I ran that failed?"

atuin mcp install registers the server for your user, so it works in every project, and it uses the full path to atuin, so the agent doesn't need it on its PATH. Running it again is safe, and updates the path if atuin has moved.

Setting it up by hand

The server runs over stdio: your agent starts it when it needs it, so there's nothing to keep running. Every agent just needs to run this command:

atuin mcp

Editors and desktop apps often don't get your shell's PATH. If one can't find atuin, replace atuin below with the full path that which atuin prints.

Claude Code

claude mcp add --scope user atuin -- atuin mcp

Check it with claude mcp list, or /mcp inside Claude Code.

Codex

codex mcp add atuin -- atuin mcp

Or add it to ~/.codex/config.toml yourself:

[mcp_servers.atuin]
command = "atuin"
args = ["mcp"]

Grok Build

grok mcp add atuin -- atuin mcp

Or add it to ~/.grok/config.toml yourself:

[mcp_servers.atuin]
command = "atuin"
args = ["mcp"]

Hermes Agent

hermes config set mcp_servers.atuin '{"command": "atuin", "args": ["mcp"], "env": {}}'

This adds the server to the config.yaml of the Hermes home that hermes uses (by default ~/.hermes/config.yaml, or the active profile's), keeping the rest of the file and its comments; atuin mcp install hermes runs the same command for that home, with the full path to atuin. hermes mcp add asks whether to turn on the server's tools, so it needs a terminal. A running Hermes gateway picks the server up within about a minute, with no restart. Check it with hermes mcp list. Each profile has its own config.yaml: to add the server to another, run the command with hermes -p <name>, or atuin mcp install hermes with HERMES_HOME set to the profile's directory (~/.hermes/profiles/<name>).

Hermes doesn't run the server with your shell's PATH, so if it can't find atuin, use the full path from which atuin:

mcp_servers:
  atuin:
    command: /full/path/to/atuin
    args: ["mcp"]
    env: {}

Hermes gives an MCP server only a few of its environment variables (PATH, HOME, XDG_* and some others), never ATUIN_* ones. To make up for that, atuin mcp install hermes copies the ATUIN_* settings in your shell that say where Atuin's config and data are into the server's env: those ending in _HOME, _DIR or _PATH, such as ATUIN_HOME, ATUIN_CONFIG_DIR or ATUIN_DB_PATH. It copies nothing else, so no secret reaches Hermes's config. Run it again after you change one. If your config's paths use other variables, such as $HISTDIR, or you set the server up by hand, add them to its env yourself, or it reads the default Atuin data:

hermes config set mcp_servers.atuin.env '{"ATUIN_CONFIG_DIR": "/path/to/config"}'

Hermes names the tools mcp__atuin__atuin_history and so on.

Kiro CLI

kiro-cli mcp add --name atuin --command atuin --args mcp --scope global

This adds it to ~/.kiro/settings/mcp.json (under $KIRO_HOME if you have set it), which every session loads; atuin mcp install kiro writes the same file without going through kiro-cli. Check it with kiro-cli mcp list. Kiro doesn't run the server with your shell's PATH, so if it can't find atuin, use the full path from which atuin:

{
  "mcpServers": {
    "atuin": {
      "command": "/full/path/to/atuin",
      "args": ["mcp"],
      "env": {}
    }
  }
}

opencode

Add it to ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "atuin": {
      "type": "local",
      "command": ["atuin", "mcp"],
      "enabled": true
    }
  }
}

Check it with opencode mcp list.

pi

pi 1.0 and later:

pi mcp add atuin -- atuin mcp

This adds it to ~/.pi/agent/mcp.json. Check it with pi mcp list.

Cursor

Add it to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "atuin": {
      "command": "atuin",
      "args": ["mcp"]
    }
  }
}

VS Code (GitHub Copilot)

code --add-mcp '{"name":"atuin","command":"atuin","args":["mcp"]}'

Gemini CLI

gemini mcp add --scope user atuin atuin mcp

Claude Desktop

Open Settings → Developer → Edit Config, and add the server to claude_desktop_config.json. Claude Desktop doesn't get your shell's PATH, so use the full path from which atuin:

{
  "mcpServers": {
    "atuin": {
      "command": "/full/path/to/atuin",
      "args": ["mcp"]
    }
  }
}

Then quit and reopen Claude Desktop.

Zed

Add it to Zed's settings.json:

{
  "context_servers": {
    "atuin": {
      "command": "atuin",
      "args": ["mcp"]
    }
  }
}

Windsurf

Add it to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "atuin": {
      "command": "atuin",
      "args": ["mcp"]
    }
  }
}

Anything else

Most MCP clients take a config like Cursor's above: a server named atuin that runs the command atuin with the argument mcp.

Tools

atuin_history

Searches your shell history. Commands containing every search term come first, and the rest of the page is filled with fuzzy matches (the same matching as the search TUI), marked as such. Each result includes the command, when and where it ran, its exit code, and its duration, along with a history ID that can be passed to atuin_output.

Searches can be narrowed down in a few ways:

• Filter mode: the same scopes as interactive search — global (the default), host, directory, workspace, or session. The directory and workspace scopes are relative to the directory your MCP client launched the server in, which for most editors is your project directory.
• Failed commands only: return only commands that exited with a non-zero exit code.
• Author: filter to commands you ran yourself, commands run by AI agents, or commands run by one specific agent. See AI Agent Hooks for how Atuin records agent-run commands.

History search reads the Atuin database directly, so it works without any extra setup.

atuin_output

Fetches the captured terminal output of a previous command, identified by a history ID from atuin_history results. The agent can fetch specific line ranges, so it doesn't need to read a huge log to find the error at the end.

Output capture requires the daemon and pty-proxy to be running — see Capturing Command Output for setup. Without them, the tool responds with an error explaining that no output is available.

atuin_output_search

Searches the captured output of every command, for when the agent knows what was printed but not which command printed it — an error message, a version string, a hostname. It's the same search as atuin output search, with each term in place of an argument: terms are matched as whole words and all of them must appear, and the words of one term must appear together, in that order.

Each result gives the command and its history metadata, followed by the output lines around each match with their line numbers, so the agent can pass the history ID and a line range to atuin_output to read more.

Like atuin_output, this needs output capture set up and the daemon running.

atuin_threads_search, atuin_threads_list and atuin_threads_read

Search, list and read your threads: the sessions of your coding agents (Claude Code, Codex, Copilot, Hermes Agent, Kiro CLI, opencode and pi) that Atuin has captured. An agent can pick up where another left off, or check what was decided last time, without you explaining it again.

These need thread capture turned on with atuin config enable threads.