ima-mcp-server

给你的自建智能体接上 IMA 的「大脑」

将 IMA 知识库 的核心能力——RAG 语义检索 + 知识图谱推理 + LLM 生成——通过标准 MCP 协议暴露出来，让任何个人开发的 AI Agent 都能直接调用。

核心亮点：ask_knowledge_base

这是整个项目的灵魂工具。一句话：把你的知识库变成一个可对话的专家。

用户输入问题
    ↓
ask_knowledge_base 自动完成：
  ① 语义检索 → 在知识库中找到最相关的文档片段
  ② 知识图谱 → 关联实体、概念，补全上下文
  ③ LLM 生成 → 基于检索结果生成带引用的回答
  ④ 引用增强 → 自动下载前 3 条引用文件的完整内容
    ↓
返回：结构化答案 + 引用来源 + 文件内容

这本质上就是 IMA 产品内部的完整 RAG 管线，通过 MCP 协议直接接入到你自己的 Agent 中。你的自建智能体不再只是一个"聊天机器人"，而是真正拥有了一个能检索、能推理、能引用的知识后台。

适用场景

• 🤖 个人知识助手：把自己积累的文档/笔记/网页变成可问答的知识库

• 🏭 企业内部知识库：将 SOP、产品文档、技术规范接入 Agent，实现智能问答

• 📚 学习与研究：论文、教材、课程笔记导入后，随时提问和交叉检索

• 🔧 开发者工具链：API 文档、设计规范、代码仓库接入，让 Coding Agent 直接查阅

项目亮点一览

入口文件

项目提供两个等效的入口文件：

两个文件内容完全一致，任选其一即可。

运行方式：本地 stdio

本项目是一个命令行 MCP 服务器，通过 stdin/stdout 与 MCP 客户端通信。它不是网络服务——不需要启动端口、不需要远程访问，在你的 MCP 客户端配置中指定 node server.js（或 node server.mjs）即可。

你的 Agent 平台（如 Claude Desktop、Cursor）
    │
    │  启动子进程：node server.js
    │  通过 stdin 发送 JSON-RPC 请求
    │  通过 stdout 接收 JSON-RPC 响应
    ▼
┌─────────────────────────────────┐
│  ima-mcp-server (Node.js)       │
│  ├─ OpenAPI 认证 → ima.qq.com   │
│  └─ Cookie 认证 → ima.qq.com    │
└─────────────────────────────────┘

优点：无需公网 IP、无需部署服务器、凭证不出本地机器。

快速开始

1. 前置要求

• Node.js ≥ 18（内置 fetch，无需额外安装）

• IMA 账号（用 QQ/微信登录 https://ima.qq.com）

2. 安装

git clone https://github.com/qqpp13465/ima-mcp-server.git
cd ima-mcp-server
npm install

3. 获取凭证

项目需要两类凭证，按你使用的工具选择配置：

获取 OpenAPI 凭证（必须）

1. 浏览器打开 https://ima.qq.com → 登录你的 QQ/微信账号

2. 访问 https://ima.qq.com/agent-interface

3. 点击「创建凭证」，复制 Client ID 和 API Key

获取 IMA_COOKIE（如需 RAG 问答）

只有 ask_knowledge_base 和 list_knowledge_bases_full 需要 Cookie 认证。如果只需要文件读写，只配 OpenAPI 凭证就够了。

1. 浏览器打开 https://ima.qq.com ，登录你的 QQ/微信账号

2. 按 F12 打开开发者工具，切换到 Network（网络） 标签

3. 在 IMA 页面中点击任意知识库，进行一次提问

4. 在 Network 中找到发往 /cgi-bin/assistant/qa 的请求，点击查看详情

5. 在 Request Headers 中找到 x-ima-cookie 字段，复制完整值

6. 将复制的内容作为 IMA_COOKIE 环境变量

⚠️ Cookie 会过期。如果某次调用返回 600001 错误（登录过期），项目会自动尝试用 refresh token 续期。如果自动续期也失败，需重新按上述步骤获取 Cookie。

4. 配置 MCP 客户端

以 Claude Desktop 为例，编辑 claude_desktop_config.json：

{
  "mcpServers": {
    "ima": {
      "command": "node",
      "args": ["C:\\Users\\你的用户名\\ima-mcp-server\\server.js"],
      "env": {
        "IMA_CLIENT_ID": "你的_client_id",
        "IMA_API_KEY": "你的_api_key",
        "IMA_COOKIE": "你的_x-ima-cookie值"
      }
    }
  }
}

注意：Windows 路径用 \\（JSON 转义），macOS/Linux 用 /。

.js vs .mjs：如果你的 MCP 客户端不支持 .mjs 扩展名（部分国产 Agent 平台有此限制），只需将 server.js 换成 server.mjs 即可，内容完全一致。

5. 验证

重启 MCP 客户端后，对 Agent 说：

"列出我的所有知识库"

返回知识库列表即配置成功。

可用工具

📌 关于已删除的工具：本项目移除了 IMA 官方 OpenAPI 中的 search_knowledge_base、get_knowledge_base、get_knowledge_list 三个读取工具，因为它们的功能已被 ask_knowledge_base（RAG 语义检索 + 知识图谱 + LLM 生成）完全覆盖且体验更好。如果你仍需要原生的关键字搜索或列表分页功能，可参考 IMA 官方 API 文档 自行在 server.js 中添加。

所有 MCP 客户端配置参考

以下配置请将路径和凭证替换为实际值。

Claude Desktop

配置文件：%APPDATA%\Claude\claude_desktop_config.json (Windows) / ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)

Cursor

配置文件：~/.cursor/mcp.json（全局）或项目内 .cursor/mcp.json

Cline (VS Code)

在 Cline 设置 → MCP Servers → 添加

WorkBuddy

编辑 ~/.workbuddy/mcp.json，在 mcpServers 中添加 ima 条目 → 连接器管理页面点击「Trust」

通用配置模板

{
  "mcpServers": {
    "ima": {
      "command": "node",
      "args": ["/path/to/ima-mcp-server/server.js"],
      "env": {
        "IMA_CLIENT_ID": "你的_client_id",
        "IMA_API_KEY": "你的_api_key",
        "IMA_COOKIE": "你的_x-ima-cookie值（可选，用于 RAG 问答）"
      }
    }
  }
}

局限性

坦率列出当前版本的限制，帮助你判断是否适用：

故障排查

安全说明

• 凭证不出本地：所有凭证仅通过 HTTP 头发送至 ima.qq.com，不发送到任何第三方

• 容器化你的凭证：建议在 MCP 客户端配置中通过 env 传入凭证，不要在代码中硬编码

• git 安全：.gitignore 已配置忽略 node_modules/、日志文件和 IDE 配置，不会意外提交敏感信息

License

MIT