Atuin 内置 MCP Server 接入指南让 Claude Code、Cursor 等 AI 工具直接检索你的 Shell 历史【免费下载链接】atuin✨ Making your shell magical项目地址: https://gitcode.com/gh_mirrors/at/atuinAtuin 内置了一个基于 MCPModel Context Protocol 协议的服务端通过atuin mcp一条命令即可把外部 AI 工具如 Claude Code、Cursor与你的 Shell 历史连接起来。读完本文你将掌握 MCP server 的启动与三种主流客户端的接入配置、atuin_history与atuin_output两个工具的参数细节与使用场景以及输出捕获、AI Agent Hooks 等前置依赖的完整搭建方法。什么是 Atuin 的 MCP ServerMCPModel Context Protocol是一个开放的协议用于把外部工具的能力以统一的方式暴露给 AI 应用。Atuin 在二进制中直接内置了一个 MCP server让 Claude Code、Cursor、Claude Desktop 等 MCP 客户端能够访问你的 Shell 历史查命令Agent 可以搜索你过去运行过的命令确认某条命令是否执行过、是否成功看输出在配置了命令输出捕获的前提下Agent 还能读取这些命令实际打印的内容例如定位一条失败命令的真实报错。该服务端暴露的历史工具与 Atuin AI 内部使用的是同一套实现。两个工具都是只读的它们无法修改或删除你的历史记录所有数据都保留在你的本机。这一点在源码中有明确的测试约束——crates/atuin-ai/src/mcp.rs中的tool_definitions_list_both_tools_as_read_only测试会断言两个工具都带上了read_only注解并且输入 schema 中唯一必填的参数只有query。启动 MCP ServerMCP server 运行在stdio标准输入输出之上也就是说它没有常驻后台进程而是由你的 MCP 客户端按需拉起。你只需要知道启动命令是atuin mcp在源码层面这条命令对应 client.rs 中定义的Mcp子命令CLI 帮助文本为 Start an MCP server exposing history search to AI tools (stdio)它仅在编译时启用了aifeature 的情况下可用实际执行时调用 mcp.rs 中的run(db)函数——该函数基于官方rmcpSDK 构建服务端并通过rmcp::transport::stdio()传输一直服务到客户端断开连接。一个重要的实现细节由于 stdout 上只允许出现 JSON-RPC 协议消息任何日志或错误输出都会走 stderr否则会破坏协议流。这一点由 mcp.rs 中run函数的注释明确说明。Claude Codeclaude mcp add atuin -- atuin mcp执行后Claude Code 会把atuin注册为一个名为atuin的 MCP server。Cursor、Claude Desktop 及其他客户端绝大多数 MCP 客户端接受如下 JSON 配置{ mcpServers: { atuin: { command: atuin, args: [mcp] } } }如果atuin可执行文件不在你客户端的PATH中请把command换成二进制文件的完整路径例如{ mcpServers: { atuin: { command: /home/you/.atuin/bin/atuin, args: [mcp] } } }工具一atuin_history历史搜索atuin_history用于搜索你的 Shell 历史使用与搜索 TUI 相同的模糊匹配算法。每条结果包含命令本身、运行时间与地点所在主机/目录、退出码、耗时以及一个可传递给atuin_output的history IDUUID。搜索可以通过若干参数进行收窄。下表整理了工具输入 schema 中定义的完整参数对应 mcp.rs 中的工具定义参数类型默认值说明querystring必填模糊搜索关键词多个词之间是 AND 关系空字符串返回最近的命令filter_modesstring[]global搜索范围取数组第一项生效limitinteger10最多返回的结果数范围 1~50only_failedbooleanfalse只返回退出码非零失败的命令仍在运行、尚未记录退出码的命令会被排除authorsstring[]无不按作者过滤按命令执行者过滤多项之间是 OR 关系过滤模式filter_modesfilter_modes支持与交互式搜索相同的五种范围对应源码中的HistorySearchFilterMode枚举见 tools/mod.rsglobal默认全部历史host仅本机directory仅当前工作目录workspace仅当前 git 仓库内运行过的命令session仅启动本 server 的那个 Shell 会话。其中directory与workspace是相对于MCP 客户端启动 server 时所在的目录解析的——对大多数编辑器而言那就是你的项目目录。一个值得注意的源码细节filter_modes在 JSON 里被设计为可省略传null也视为未提供缺省即全局搜索。这一选择有明确的工程依据——tools/mod.rs 的注释指出评测发现如果强制模型每次调用都必须选择搜索范围模型反而会干脆不调用这个工具。另外当选择session范围但环境变量$ATUIN_SESSION为空时工具会返回错误提示改用其他范围而不是静默返回空结果避免把没有会话误读成没有历史。查询语法query支持 fzf 风格的操作符按空格分隔的每个词独立生效^prefix前缀匹配suffix$后缀匹配exact-substring精确子串匹配!negate取反排除包含该词的命令r/regex/正则匹配。仅看失败命令与按作者过滤排查问题时可以设置only_failed: true只获取退出码非零的命令authors支持$all-user你自己运行的所有命令和$all-agent所有 AI Agent 运行的命令也可以填具体的 Agent 名claude-code、codex、copilot、opencode、pi见 history.rs。Agent 运行的命令如何被记录见下文AI Agent Hooks一节。无需额外配置即可使用历史搜索是直接读取 Atuin 的 SQLite 数据库完成的不依赖 daemon因此开箱即用。从源码看AtuinHistoryToolCall::execute直接对Sqlite数据库执行模糊搜索DbSearchMode::Fuzzy只有在结果为空时会返回带有放宽搜索条件建议的提示信息帮助模型调整重试策略见 tools/mod.rs。工具二atuin_output读取命令输出atuin_output根据atuin_history返回的 history ID抓取某条历史命令被捕获的终端输出。Agent 可以指定行区间这样就不必为了看日志末尾的错误而读取整份巨型日志。参数说明参数类型默认值说明history_idstring必填历史条目 IDUUID来自atuin_history结果rangesinteger[][]全部输出可选的行区间[start, end]0 起、end 闭区间负索引从输出末尾倒数ranges采用 Python 风格的索引语义这是 MCP 协议规定的。例如[[-80, -1]]表示输出末尾的最后 80 行——tools/mod.rs 中的工具描述建议模型排查失败时优先取末尾因为错误信息通常打印在最后。不传ranges时等价于[[0, -1]]即整个输出。前置条件输出捕获atuin_output不是开箱即用的。命令输出默认不会被捕获需要同时满足两个条件daemon在内存中保存最近的命令输出pty-proxy从你的终端捕获命令输出。缺少它们时工具会返回一条解释没有可用输出的错误。具体而言tools/mod.rs 中的AtuinOutputToolCall::execute在无法连接 daemon 时会返回错误并附带提示如果命令安全且代价低可以重跑一次来获取输出否则就依赖历史元数据退出码、耗时做判断——这个提示刻意不鼓励无条件重跑命令以避免重复执行破坏性命令。完整的搭建步骤请参考读取命令输出第一步启用 daemon。在 Atuin 配置文件默认~/.config/atuin/config.toml中添加[daemon] enabled true autostart trueautostart true时 Atuin 会自动启动并托管 daemon如果想用 systemd 等方式自行管理可参考 daemon 文档。第二步启用 pty-proxy。将 pty-proxy 的 init 行加入 Shell 的初始化脚本位置尽量靠前并且必须在正常的atuin init之前# zsh eval $(atuin pty-proxy init zsh)# bash eval $(atuin pty-proxy init bash)# fish加入 ~/.config/fish/config.fish 的 is-interactive 块 atuin pty-proxy init fish | source# Nushell在 config.nu 中、普通 atuin init 之前 source mkdir ~/.local/share/atuin/ atuin pty-proxy init nu | save -f ~/.local/share/atuin/pty-proxy-init.nuNushell 的详细做法可参考 pty-proxy 文档其中还包含atuin不在 PATH 时如何处理。第三步重启你的 Shell。打开新终端或重新 source 配置后pty-proxy 会捕获该会话中每条命令的输出。输出捕获的隐私与保留策略关于捕获输出以下事实值得了解详见读取命令输出捕获的输出保存在本机内存中daemon 每条命令最多保留 1MB 输出、每个 Shell 会话保留最近 128 条命令合计最多 32MB单条命令输出超过 1MB 时保留开头 512KB 和结尾 512KB通常是最相关的部分daemon 停止后输出即丢失只有 daemon 运行期间捕获的命令才可用删除历史条目时其捕获输出也会一并删除只有进入历史history的命令才会保留输出——例如store_failed false时未记录的失败命令其输出同样会被丢弃Atuin 在 LLM 主动请求某条具体命令的输出之前不会发送任何数据。可选但推荐AI Agent Hooksatuin_history的authors过滤依赖 Atuin 记录 Agent 运行的命令。安装对应 Agent 的 hook 即可做到这一点# Claude Code atuin hook install claude-code # Codex atuin hook install codex # opencode atuin hook install opencode # pi atuin hook install pihook 机制的原理是Agent 在执行 Bash 命令前触发PreToolUseAtuin 记录命令、工作目录和时间戳等同于history start命令结束后触发PostToolUse/PostToolUseFailure记录退出码与耗时等同于history end。opencode 与 pi 这类以扩展方式接入的 Agent 则直接调用atuin history start/atuin history end。更完整的说明与验证方法见 AI Agent Hooks。从源码看它的工作方式围绕atuin mcp命令crates/atuin-ai/src/mcp.rs提供了几个值得注意的实现细节Server 级指令注入。MCP server 在初始化握手时通过SERVER_INSTRUCTIONS常量向客户端提供一份指令文本Claude Code 等客户端会将其注入模型的 system prompt。这份指令明确要求 Agent 优先使用atuin_history而非猜测、询问用户或重跑命令并指出不要使用history、~/.bash_history、~/.zsh_history它们在非交互 Shell 中通常为空或过期且缺少退出码和输出。由于该文本每次会话都会注入源码中的测试server_info_carries_instructions会约束它的长度必须小于 2000 字符。协议实现。server 通过rmcpSDK 实现ServerHandlertraitlist_tools返回静态构建的工具元数据含 schema 与描述call_tool将请求分发给AtuinHistoryToolCall或AtuinOutputToolCall执行并把结果统一封装为 MCP 的CallToolResult。工具描述与 schema 均来自 tools/mod.rs 中的同一套实现与 Atuin AI 内部完全一致。只读承诺。两个工具都带read_only注解且从工具调用链看atuin_history只读数据库、atuin_output只与 daemon 通信取数均无任何写路径。常见问题与注意事项session范围失效session过滤模式只有在 MCP server 从Atuin 启用的 Shell 会话内部启动时才可用。编辑器类客户端通常从会话外部启动此时会报无会话可用的错误改用其他过滤模式即可正常工作。atuin不在 PATH 中配置 MCP 客户端时使用二进制文件的绝对路径例如~/.atuin/bin/atuin。输出读不到先确认 daemon 已启用且 pty-proxy 的 init 行已正确加入并重启了 Shell再检查对应命令是否是在 daemon 运行期间执行的。开启aifeatureatuin mcp子命令在编译时受aifeature 控制见 client.rs使用发行版预编译二进制通常已包含该能力若从源码自行构建请确保开启对应 feature。【免费下载链接】atuin✨ Making your shell magical项目地址: https://gitcode.com/gh_mirrors/at/atuin创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考