Claude Code Conversation Search MCP

不再丢失你的Claude Code对话。 再也不用问“我们在哪里讨论过那个bug修复？”或者在终端关闭时丢失数小时的上下文。

npm install -g claude-code-conversation-search-mcp

在所有项目中查找任何对话：

"我们在哪里讨论了数据库问题？"
"找到那个身份验证对话"
"昨天讨论过的Docker配置"

获取确切的项目、日期和命令以立即恢复。

你需要这个的原因

问题： Claude Code没有对话搜索功能。当你关闭终端或切换项目时，找到那个重要讨论变得不可能。你只能滚动浏览晦涩的对话标题，希望认出正确的那个。

解决方案： 在任何项目会话中搜索所有Claude Code对话。询问“我们在哪里讨论了身份验证？”并立即获得确切的对话和恢复命令。

特性

• 找回丢失的对话：再也不丢失重要的讨论
• 跨所有项目搜索：在项目A工作但需要项目B的信息？只需搜索
• 立即恢复：获取精确的claude --resume命令以继续你离开的地方
• 自然语言：像询问人类一样提问——“找到那个Docker对话”
• 闪电般快速：在毫秒内搜索数千个对话
• 零配置：安装后立即与现有的Claude Code一起工作

快速开始

安装后它会自动配置与Claude Code：

npm install -g claude-code-conversation-search-mcp

在任何项目中工作时跨所有项目进行搜索。

🎯 推荐：增强Claude Code集成

为了获得最佳搜索结果和更好的Claude Code交互，在全局~/.claude/CLAUDE.md文件中添加以下指令：

# 添加到 ~/.claude/CLAUDE.md
echo "- 当被要求使用conversation-search时，必须从非常宽泛的查询开始，逐步缩小范围。根据此MCP结果输出可读文本而不是格式化的JSON。" >> ~/.claude/CLAUDE.md

为什么这有帮助：

• 更好的搜索策略：Claude将从广泛的查询开始，并逐步缩小范围，找到更多相关的结果
• 可读的输出：你将获得带有项目路径、日期和恢复命令的正确格式化响应，而不是原始JSON
• 改进的用户体验：使对话搜索在Claude Code工作流程中感觉自然且直观

使用方法

# 找回丢失的对话
"我们在哪里讨论了登录错误？"
"找到那个Docker对话"
"我们讨论过的数据库设置"

# 按记忆搜索
"我们修复的身份验证错误"
"昨天讨论的API端点"
"上周的性能问题"

# 从其他项目中寻找解决方案
"我们是如何解决CORS问题的？"
"起作用的Redis配置"
"我们编写的部署脚本"

每次搜索都会给你：

• 对话所在的哪个项目
• 发生的时间（日期和时间）
• 讨论的内容（对话摘要）
• 恢复的智能快捷方式：cd ~/.cs/project-name && claude --resume abc123

智能目录快捷方式

搜索会自动生成目录快捷方式以加快导航速度：

• 跨平台：适用于macOS、Linux和Windows
• 短路径：使用~/.cs/代替长项目路径
• 实际目录：创建实际的符号链接/连接，你可以cd进入
• 基于项目的名称：使用有意义的名称如poc-fbf-v023-1-cc
• 自动创建：在搜索过程中按需生成

示例：

# 而不是：
cd '/Users/username/very/long/path/to/project'

# 你会得到：
cd ~/.cs/project-name

技术细节

使用TypeScript构建，使用SQLite FTS5进行搜索，通过模型上下文协议集成。

系统需求：

• Node.js 18+
• 支持MCP的Claude Code
• macOS、Linux或Windows

性能：

• 在10k+对话中进行亚秒级搜索
• 实时索引，通过文件监控
• 极小的内存占用（约50MB）

存储：

• SQLite数据库位于~/.claude/conversation-search/
• 索引对话内容，而非文件内容
• 自动清理已删除的对话

安装

从源代码安装

# 克隆仓库
git clone https://github.com/TonySimonovsky/claude-code-conversation-search-mcp.git
cd claude-code-conversation-search-mcp

# 安装依赖
npm install

# 构建项目
npm run build

# 可选：全局链接
npm link

配置

自动设置（推荐）

安装后，MCP服务器会自动配置与Claude Code。无需手动配置！

手动配置（可选）

如果你需要自定义配置，请选择以下方法之一：

选项1：命令行（推荐）

# 对所有项目全局添加
claude mcp add conversation-search claude-code-conversation-search-mcp

# 仅对当前项目添加（创建.mcp.json）
claude mcp add --scope project conversation-search claude-code-conversation-search-mcp

选项2：直接编辑配置文件

全局配置（所有项目）：

# 编辑全局Claude Code配置（从任何地方运行）
nano ~/.claude.json
# 或使用你喜欢的编辑器：code ~/.claude.json

{
  "mcpServers": {
    "conversation-search": {
      "command": "claude-code-conversation-search-mcp",
      "args": []
    }
  }
}

特定项目的配置（团队共享）：

# 创建项目配置文件（从项目根目录运行）
nano .mcp.json
# 或：code .mcp.json

{
  "mcpServers": {
    "conversation-search": {
      "command": "claude-code-conversation-search-mcp",
      "args": []
    }
  }
}

配置选项

MCP服务器支持通过环境变量进行广泛的配置。这里是最常用的选项：

环境变量	描述	默认值
CONVERSATION_DB_PATH	SQLite数据库路径	~/.claude/conversation-search.db
CLAUDE_PROJECTS_DIR	Claude项目目录路径	~/.claude/projects
INDEX_INTERVAL	自动索引间隔（毫秒）	300000（5分钟）
MAX_RESULTS	返回的最大搜索结果数	20
DEFAULT_CONTEXT_SIZE	默认上下文消息数量（前后）	2
AUTO_INDEXING	启用自动索引	true
DEBUG	启用调试日志	false

📖 有关完整的配置选项和性能调优，请参阅配置指南

使用方法

配置完成后，可以在Claude Code中使用以下工具：

搜索对话

使用自然语言搜索您的对话历史：

search_conversations("我们在哪里创建了auth.js？")
search_conversations("上周的数据库优化")
search_conversations("index.ts中的TypeError")

查询示例：

• 文件操作："创建auth.js"，"编辑config.json"，"修改database.ts"
• 主题："讨论React钩子"，"安全审查"，"性能优化"
• 错误："TypeError"，"CORS错误"，"未定义的变量"
• 命令："npm install lodash"，"git commit"，"数据库迁移"
• 时间过滤器："今天"，"昨天"，"上周"，"本月"
• 项目过滤器："在项目myapp中"，"来自backend-api"

参数：

• query（必需）：自然语言搜索查询
• limit（可选）：返回的最大结果数（默认：110）
• includeContext（可选）：是否包含周围的消息（默认：true）

列出项目

获取所有已索引项目的统计信息：

list_projects()

返回项目名称、消息数量和最后活动日期。

获取消息上下文

检索特定消息周围的完整上下文：

get_message_context("msg_abc123", contextSize: 5)

参数：

• messageId（必需）：要获取上下文的消息ID
• contextSize（可选）：前后消息的数量（默认：5）

获取对话消息

从特定对话中检索消息：

get_conversation_messages("conv_456", limit: 50, startFrom: 0)
get_conversation_messages("conv_456", limit: 10, startFrom: -1)  # 最后10条消息
get_conversation_messages("conv_456", limit: 20, startFrom: -10) # 从末尾第10条开始的20条消息

参数：

• conversationId（必需）：要获取消息的对话ID
• limit（可选）：返回的消息数量（默认：50）
• startFrom（可选）：起始位置 - 0=第一个，-1=最后一个，-10=从末尾第10个开始（默认：0）

列出工具

显示所有可用工具及其签名：

list_tools()

返回自动生成的工具签名和描述。当添加新工具时会自动更新。

刷新索引

手动触发重新索引：

refresh_index()

在添加新项目或禁用自动索引后很有用。

获取服务器信息

显示服务器版本、变更日志和系统信息：

get_server_info()

显示当前版本、最近更改、系统状态和可用工具。

高级用法

复杂查询

内置查询解析器支持复杂的自然语言模式：

# 查找特定的文件操作
"我们在哪里创建或修改了认证文件？"

# 根据多个标准搜索
"上周在项目backend中的数据库迁移"

# 查找特定的错误模式
"React组件中的TypeError或ReferenceError"

# 搜索工具操作
"包含npm或yarn的bash命令"

# 查找代码讨论
"我们在哪里讨论了实现缓存的问题？"

搜索运算符

• AND：术语默认是AND关系（"auth login"查找同时包含两个词的消息）
• OR：在术语之间使用"or"（"auth or login"）
• NOT：使用"-"前缀（"auth -test"排除与测试相关的结果）
• 短语：使用引号表示精确短语（"用户认证"）
• 通配符：使用*进行前缀匹配（"auth*"匹配auth、authentication等）

时间过滤器

支持的时间表达式：

• 今天，昨天
• 上周，本周
• 上个月，本月
• 过去7天，过去30天
• 具体日期："2024-01-15"，"自1月1日起"

开发

设置开发环境

# 克隆并安装
git clone <repository>
cd claude-code-conversation-search-mcp
npm install

# 开发模式下运行，支持热重载
npm run dev

# 运行测试
npm test

# 为生产构建
npm run build

项目结构

src/
├── index.ts              # MCP服务器入口点
├── indexer/
│   ├── parser.ts        # JSONL对话解析器
│   ├── database.ts      # SQLite数据库操作
│   └── indexer.ts       # 索引编排
├── search/
│   └── query.ts         # 自然语言查询解析器
└── types/
    └── index.ts         # TypeScript类型定义

贡献

1. 分叉仓库
2. 创建特性分支（git checkout -b feature/amazing-feature）
3. 提交更改（git commit -m '添加惊人的特性'）
4. 推送到分支（git push origin feature/amazing-feature）
5. 打开拉取请求

故障排除

数据库问题

如果搜索索引损坏：

# 删除数据库文件
rm ~/.claude/conversation-search.db

# 重启Claude Code以触发重新索引

性能优化

对于大量的对话历史：

1. 增加INDEX_INTERVAL以减少索引频率
2. 设置MAX_RESULTS以限制结果大小
3. 在查询中使用特定的项目过滤器

调试模式

启用调试日志以排查问题：

{
  "mcpServers": {
    "conversation-search": {
      "command": "npx",
      "args": ["claude-code-conversation-search-mcp"],
      "env": {
        "DEBUG": "true"
      }
    }
  }
}

许可证

MIT许可证 - 详情见LICENSE文件

致谢

使用Anthropic的模型上下文协议SDK构建。

作者

Tony AI Champ & Claude Code，2025年9月

支持

对于问题、功能请求或疑问：

• 在GitHub上打开一个issue
• 查看现有issue以寻找解决方案
• 报告错误时包括调试日志