claude-code-conversation-search-mcp

Claude Code Conversation Search MCP

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

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

查找所有项目中的任意对话：

"where did we discuss the database issue?"
"find that authentication conversation"
"docker configuration we talked about yesterday"

获取确切的项目、日期和命令，即刻恢复对话。

为什么需要它

问题： 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 文件中：

# Add to ~/.claude/CLAUDE.md
echo "- When asked to use conversation-search, you must start searching from very wide queries, narrowing down step by step. When responding based on this mcp results output a human readable text with proper newlines instead of formatting json." >> ~/.claude/CLAUDE.md

这样做的好处：

• 更好的搜索策略：Claude 会先使用宽泛的查询，然后逐步缩小范围，从而找到更多相关结果
• 易于阅读的输出：你将获得格式规范的响应，其中包含项目路径、日期和恢复命令，而不是原始 JSON
• 改善用户体验：让 Claude Code 工作流中的对话搜索变得自然直观

用法

# Find lost conversations
"where did we discuss the login bug?"
"find that Docker conversation"
"database setup we talked about"

# Search by what you remember
"authentication error we fixed"
"API endpoint discussion yesterday"
"performance issue last week"

# Find solutions from other projects  
"how did we solve CORS issues?"
"Redis configuration that worked"
"deployment script we wrote"

每次搜索都会显示：

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

智能目录快捷方式

搜索会自动创建目录快捷方式，方便快速导航：

• 跨平台：适用于 macOS、Linux 和 Windows
• 短路径：使用 ~/.cs/ 代替冗长的项目路径
• 真实目录：创建可供 cd 进入的实际符号链接／联接
• 基于项目命名：使用 poc-fbf-v023-1-cc 等易懂名称
• 自动创建：搜索时按需生成

示例：

# Instead of:
cd '/Users/username/very/long/path/to/project'

# You get:
cd ~/.cs/project-name

技术信息

使用 TypeScript 构建，采用 SQLite FTS5 进行搜索，并通过 Model Context Protocol 集成。

系统要求：

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

性能：

• 亚秒级搜索 1 万多条对话
• 通过文件监视实时建立索引
• 内存占用极低（约 50MB）

存储：

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

安装

从源代码安装

# Clone the repository
git clone https://github.com/TonySimonovsky/claude-code-conversation-search-mcp.git
cd claude-code-conversation-search-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Optional: Link globally
npm link

配置

自动设置（推荐）

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

手动配置（可选）

如果需要自定义配置，请选择以下任一方式：

选项 1：命令行（推荐）

# Add globally for all projects
claude mcp add conversation-search claude-code-conversation-search-mcp

# Add for current project only (creates .mcp.json)
claude mcp add --scope project conversation-search claude-code-conversation-search-mcp

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

全局配置（所有项目）：

# Edit the global Claude Code config (run from anywhere)
nano ~/.claude.json
# Or use your preferred editor: code ~/.claude.json

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

项目专属配置（团队共享）：

# Create project config file (run from project root)
nano .mcp.json
# Or: 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("Where did we create auth.js?")
search_conversations("database optimization last week")
search_conversations("TypeError in index.ts")

查询示例：

• 文件操作："created auth.js"、"edited config.json"、"modified database.ts"
• 主题："discuss React hooks"、"security review"、"performance optimization"
• 错误："TypeError"、"CORS error"、"undefined variable"
• 命令："npm install lodash"、"git commit"、"database migration"
• 时间筛选："today"、"yesterday"、"last week"、"this month"
• 项目筛选："in project myapp"、"from backend-api"

参数：

• query（必填）：自然语言搜索查询
• limit（可选）：返回的最大结果数（默认值：10）
• 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)  # Last 10 messages
get_conversation_messages("conv_456", limit: 20, startFrom: -10) # 20 messages starting from 10th from end

参数：

• conversationId（必填）：要获取消息的对话 ID
• limit（可选）：要返回的消息数（默认值：50）
• startFrom（可选）：起始位置——0=第一条，-1=最后一条，-10=倒数第 10 条（默认值：0）

列出工具

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

list_tools()

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

刷新索引

手动触发重新索引：

refresh_index()

添加新项目后或禁用自动索引时，此功能很有用。

获取服务信息

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

get_server_info()

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

高级用法

复杂查询

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

# Find specific file operations
"Where did we create or modify authentication files?"

# Search by multiple criteria
"database migrations in project backend last week"

# Find specific error patterns
"TypeError or ReferenceError in React components"

# Search tool operations
"bash commands containing npm or yarn"

# Find code discussions
"Where did we discuss implementing caching?"

搜索运算符

• AND：默认对词项使用 AND 运算（"auth login" 可查找同时包含两者的消息）
• OR：在词项之间使用“or”（"auth or login"）
• NOT：使用 - 前缀（"auth -test" 可排除与测试相关的结果）
• 短语：使用引号精确匹配短语（"user authentication"）
• 通配符：使用 * 进行前缀匹配（"auth*" 可匹配 auth、authentication 等）

时间筛选

支持的时间表达式：

• today、yesterday
• last week、this week
• last month、this month
• last 7 days、last 30 days
• 特定日期："on 2024-01-15"、"since January 1"

开发

设置开发环境

# Clone and install
git clone <repository>
cd claude-code-conversation-search-mcp
npm install

# Run in development mode with hot reload
npm run dev

# Run tests
npm test

# Build for production
npm run build

项目结构

src/
├── index.ts              # MCP server entry point
├── indexer/
│   ├── parser.ts        # JSONL conversation parser
│   ├── database.ts      # SQLite database operations
│   └── indexer.ts       # Indexing orchestration
├── search/
│   └── query.ts         # Natural language query parser
└── types/
    └── index.ts         # TypeScript type definitions

贡献

1. Fork 此仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 提交更改（git commit -m 'Add amazing feature'）
4. 将分支推送到远程仓库（git push origin feature/amazing-feature）
5. 创建 Pull Request

故障排除

数据库问题

如果搜索索引损坏：

# Remove the database file
rm ~/.claude/conversation-search.db

# Restart Claude Code to trigger re-indexing

性能优化

对于较大的对话历史记录：

1. 增大 INDEX_INTERVAL，以降低索引频率
2. 设置 MAX_RESULTS，以限制结果数量
3. 在查询中使用具体的项目筛选条件

调试模式

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

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

许可证

MIT 许可证——详情请参阅 LICENSE 文件。

致谢

使用 Anthropic 开发的 Model Context Protocol SDK 构建。

鸣谢

由 Tony AI Champ 和 Claude Code 开发，09-2025

支持

如有问题、功能请求或疑问：

• 在 GitHub 上提交 issue
• 查看现有 issue，寻找解决方案
• 报告 bug 时，请附上调试日志