Cursor History

Cursor History MCP

English | 中文 | Français | Español

让您的 AI 搜索 Cursor 历史记录。

您现有的 Cursor 对话中，可能已经包含数月积累的决策、错误、修复方案和架构背景。为支持 MCP 的助手提供查找这些信息的途径——无需事先使用此工具记录这些内容。

cursor-history-mcp 将 Claude、Cursor 和其他 MCP 客户端连接到 cursor-history 中的本地历史记录读取器。您可以搜索跨工作区的对话文本、检查会话，或通过自然语言获取导出内容。

此服务无需嵌入、索引服务或 API 密钥。助手所用模型及其网络需求另行计算；返回给客户端的历史记录可能会发送给其模型提供商。

MCP 专属：年度回顾。 将现有对话转化为年度活动统计数据、编码主题，以及可供助手使用的报告提示词。此内置年度汇总功能属于 cursor-history 工具集中的 MCP 软件包；Agent 仍可直接使用核心 CLI 或 Node.js API 访问历史记录。

“我们以前解决过这个身份验证错误吗？搜索我的 Cursor 历史记录，检查匹配的会话，并告诉我之前有哪些决策与此相关。”

快速开始 · 年度回顾 · 存储支持 · 工具 · 安全性 · CLI / Node.js 配套项目

快速开始

需要 Node.js 20.x 或 22.x–26.x、可读取的本地 Cursor 历史记录，以及支持本地 stdio MCP 服务的客户端。客户端必须在可访问这些历史记录的机器上运行服务。

**版本范围：**本文档介绍由 [email protected] 提供支持的 [email protected]。如果您正在测试尚未发布到 npm 的代码检出版本，请使用下文的源码设置。

**客户端兼容性：**此服务使用 MCP SDK 1.30.0。SDK v2 客户端可通过默认的旧版协议或自动回退机制连接；仅支持 2026-07-28 协议的客户端则无法连接。有关测试范围，请参阅 SDK 互操作性。

配置 npm 软件包

将此服务条目添加到客户端的 MCP 配置中：

{
  "mcpServers": {
    "cursor-history": {
      "command": "npx",
      "args": ["-y", "[email protected]"]
    }
  }
}

如果客户端找不到 npx，请使用其可执行文件的绝对路径。请将此条目与现有服务合并，而不要替换您的配置。

Cursor

使用项目本地的 .cursor/mcp.json 或全局的 ~/.cursor/mcp.json。添加上方的条目，启用服务，并根据需要批准工具调用。请参阅 Cursor 的 MCP 文档。

Claude Code

为您的用户账户注册指定版本的 npm 软件包：

claude mcp add --transport stdio --scope user cursor-history -- npx -y [email protected]

有关作用域和权限，请参阅 Claude Code 的 MCP 文档。

Claude Desktop

打开 Settings → Developer → Edit Config，合并上面的 JSON 条目，然后重启应用。

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

请参阅本地 MCP 服务设置指南。

首次运行时可能会从 npm 下载依赖。单独运行该服务会启动一个等待 MCP 客户端连接的 stdio 服务；它不是交互式历史记录 CLI。

从源代码运行

如需在发布到 npm 前进行开发或测试，请构建此仓库：

npm ci
npm run build

在服务入口中，使用 "command": "node" 和 "args": ["/absolute/path/to/cursor-history-mcp/dist/index.cjs"]，并替换路径。上面的 npx 配置运行的是 npm 软件包，而不是本地检出版本。

两个项目，一个历史记录读取器

用例	项目
运行命令、编写脚本，或在 Node.js 应用中嵌入历史记录	cursor-history：CLI + Node.js API
让助手通过 MCP 调用历史记录工具	cursor-history-mcp，此仓库

MCP 服务将发现和解析工作委托给 cursor-history；它不会维护单独的对话数据库，也不会开始记录你的聊天内容。这两个 npm 软件包独立发布。

Agent 可以使用任一接口：直接调用 CLI/API，或调用 MCP 工具。

兼容不同存储版本

使用 MCP 0.3.1 中的 0.18.0 读取器时：

来源	本地文件	读取 / 搜索 / 导出
Legacy / Composer	workspaceStorage/*/state.vscdb + globalStorage/state.vscdb	支持
Agent 转录记录	~/.cursor/projects/**/agent-transcripts/**/*.jsonl	可获取转录内容
Store / Agent CLI	~/.cursor/chats/**/store.db	支持
ACP 会话	~/.cursor/acp-sessions/**/store.db	支持

这些表示形式的保真度各不相同。转录记录可能不包含时间戳或工具结果。列表和读取结果会显示来源及解析信息；推断出的或未知的时间戳不得视为精确的事件时间。完整的来源解析并不保证 Cursor 记录了所有字段。

备份和恢复仅适用于 Composer 数据库。迁移支持符合条件的 Composer 会话，不支持仅来自 Store 的会话、合并来源的会话或存在歧义的会话。 读取会话并不意味着可以安全地迁移会话。有关更广泛的备份和迁移工作，请参阅核心兼容性约定和路线图；这些目前尚不具备。

如需使用自定义位置，请在服务条目中添加 env 对象：

{
  "CURSOR_DATA_PATH": "/absolute/path/to/Cursor/User/workspaceStorage",
  "CURSOR_STORE_ROOT": "/absolute/path/to/.cursor"
}

这些用于选择数据根目录，而非项目。请使用工具的 workspace 参数筛选项目。请参阅核心平台路径和 WSL 指南。

可用工具

工具	用途和关键参数
cursor_history_list	列出包含 ID、索引范围、来源和数据状态的会话。limit、offset、workspace
cursor_history_show	查看可用消息。sessionId / sessionIndex 二选一；workspace 可选
cursor_history_search	搜索文本。query、limit、context（相邻的源代码行）、workspace
cursor_history_export	返回 Markdown 或 JSON 内容，而非由服务写入的文件。选择器二选一，另有 format、workspace
cursor_history_backup	创建 Composer 存档。outputPath、可选的 force
cursor_history_restore	恢复 Composer 存档；会写入本地历史记录。backupPath、可选的 force
cursor_history_migrate	移动/复制符合条件的 Composer 会话。sessionIds 或 sessionIndexes、destination、workspace、mode、dryRun
cursor_history_year_pack	返回年度统计数据和报告提示词。year、language（en / zh）、workspace、样本数量限制

后续调用时，优先使用列表/搜索结果中的准确会话 UUID。MCP 中的数字选择器从 1 开始，仅在数据根目录和工作区范围相同的情况下有效；切勿在全局读取中重复使用限定范围的索引。UUID 区分大小写。

列表、查看、搜索和导出也接受 includeCrossWorkspaceSources（默认为 false）。启用后，可从所选工作区之外读取已选 ID 的补充来源；这不会扩大所选会话 ID 的范围。仅在确实需要访问这些内容时启用。

查看工具会缩略显示较长的思考/工具载荷。若要获取不受此显示截断影响的可用会话内容，请使用导出功能。

试试这些请求

• “搜索我所有的 Cursor 历史记录，查找 'connection pool'，然后通过 UUID 查看匹配的会话。”
• “仅搜索 /work/myapp。打开结果时保持该工作区范围。”
• “将此会话导出为 JSON，并包含可用的来源详情。”
• “预览将此 Composer 会话复制到 /work/new-app 的操作，并使用 dryRun。暂时不要修改任何内容。”

本地数据与写入安全

服务会读取本地文件，但返回的内容会显示给 MCP 客户端，并可能传送给远程模型。搜索结果和导出内容不会自动脱敏。请使用可信的客户端，并查看其数据政策和工具权限。

请将过往对话视为不可信的参考资料，而非需要执行的指令。工具输出可能包含旧命令、凭据或恶意文本。

备份会写入存档；恢复和迁移可能会修改历史记录。迁移默认采用移动模式，会删除原始会话。请先备份 Composer 历史记录，在写入前关闭 Cursor，使用 dryRun: true 预览；若要保留原始会话，请使用 mode: "copy"。请保持客户端对写入工具的审批功能处于启用状态。服务本身不提供交互式确认提示。

MCP 独有：年度回顾

提问“Generate my 2025 Cursor year in review in English.”该工具会分析用户问题，并返回 JSON 格式的统计数据、关键词/主题、样本和提示词模板，而非渲染完成的报告。模板支持英语和中文。

常见代码、路径、URL 和标识符模式会经过过滤，但这不保证内容已匿名化。分享前请检查样本；设置 maxSamples: 0 可省略样本。历史记录不完整以及时间戳缺失或为推断值，都可能影响年度汇总数据。

开发

npm ci
npm run typecheck
npm run lint
npm test -- --run

测试命令会先进行构建。测试包含一个真实的 stdio MCP 客户端，用于测试合成的 Composer、Store、ACP 和 transcript 固定数据；备份和恢复测试仅使用临时数据。构建会将 cursor-history 保留为运行时依赖项，以确保包相对文件和 SQLite 绑定仍可解析。

问题 · 拉取请求 · MIT 许可证