Skip to main content
Glama
ima-mcp-server

ima-mcp-server

by rowanlin-dev

ima-mcp-server

将 IMA 知识库 官方 OpenAPI 封装为标准 MCP(Model Context Protocol) 服务器,可在任何支持 MCP 的 agent 软件中检索、浏览、读取知识库内容。

特性

  • ✅ 标准 MCP 协议(stdio 传输),兼容所有 MCP 客户端

  • ✅ 9 个知识库工具:搜索、浏览、读取原文、读取笔记正文、添加网页、上传本地文件

  • ✅ 凭证灵活配置(环境变量 / 配置文件)

  • ✅ 零外部服务依赖,纯 Node.js 运行

Related MCP server: agentdocs-mcp

可用工具

工具

功能

search_knowledge_base

搜索知识库列表(空 query 返回全部,含订阅库)

get_knowledge_base

获取知识库详情(描述、推荐问题)

get_knowledge_list

浏览知识库内容(根目录/文件夹,分页)

search_knowledge

在知识库内按关键词搜索文档

get_media_info

获取条目原文/下载链接;笔记类自动返回正文(note_content)

get_note_content

读取笔记正文(纯文本),传入 note_id

get_addable_knowledge_base_list

获取可添加内容的知识库列表

import_urls

将网页/微信文章添加到知识库

upload_file

上传本地文件到知识库(PDF/Word/PPT/Excel/Markdown/图片/TXT/XMind/音频/HTML 等),内部含 COS 直传与重名处理

笔记读取说明:IMA 笔记正文通过 openapi/note/v1/get_doc_content 读取。get_media_info 命中笔记(media_id 以 note_ 开头)时会自动附带 note_content 字段;也可用 get_note_content 传 note_id 直读。微信文章/网页/文件类则返回可访问 URL。

前置要求

安装

git clone <repo> ima-mcp-server
cd ima-mcp-server
npm install

或直接将 server.mjs + package.json 拷贝到本地后 npm install。

快速安装使用(AI 指令)

下面两种方式任选其一,都能在 1 分钟内把本库装好并接进 MCP 客户端。

方式一:复制命令直接跑

把下面整段粘进终端(或交给任意 AI 编码助手执行),记得替换你的 client_id / api_key:

# 1. 拉代码 + 装依赖
git clone https://github.com/rowanlin-dev/ima-mcp-server.git ima-mcp-server
cd ima-mcp-server
npm install

# 2. 写凭证(配置文件方式,最省心)
mkdir -p ~/.config/ima
printf '%s' "你的_client_id" > ~/.config/ima/client_id
printf '%s' "你的_api_key"  > ~/.config/ima/api_key
chmod 600 ~/.config/ima/client_id ~/.config/ima/api_key

# 3. 验证:应列出 9 个工具(含 upload_file)
node test-protocol.mjs

方式二:把这段指令直接丢给你的 AI

请帮我本地安装并配置 ima-mcp-server(IMA 知识库的 MCP 服务器):

  1. git clone https://github.com/rowanlin-dev/ima-mcp-server.git ima-mcp-server 后 npm install;

  2. 把 IMA 的 Client ID / API Key 写入 ~/.config/ima/client_id 和 ~/.config/ima/api_key,权限设 600;

  3. 在我的 MCP 客户端(Claude Desktop / Cursor / Cline / WorkBuddy 等)配置里加一个 ima server:command: node,args: ["<绝对路径>/ima-mcp-server/server.mjs"];

  4. 跑 node test-protocol.mjs 确认输出 9 个工具后,告诉我怎么在对话里验证(例如说“列出我的所有知识库”)。 凭证我去 https://ima.qq.com/agent-interface 取,不要写进任何仓库或日志。

各客户端的完整 JSON 配置见下文「各 MCP 客户端配置」。

凭证配置(三选一)

方式 A:环境变量(推荐,配置在 MCP 客户端中)

IMA_CLIENT_ID=你的_client_id
IMA_API_KEY=你的_api_key

方式 B:兼容 ima-skill 的环境变量名

IMA_OPENAPI_CLIENTID=你的_client_id
IMA_OPENAPI_APIKEY=你的_api_key

方式 C:配置文件

mkdir -p ~/.config/ima
echo "你的_client_id" > ~/.config/ima/client_id
echo "你的_api_key" > ~/.config/ima/api_key

优先级:方式 A > 方式 B > 方式 C

各 MCP 客户端配置

以下配置中的路径请替换为你的实际路径。

Claude Desktop

配置文件位置:

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

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

Cursor

配置文件:~/.cursor/mcp.json(全局)或项目内 .cursor/mcp.json

{
  "mcpServers": {
    "ima": {
      "command": "node",
      "args": ["/Users/你的用户名/ima-mcp-server/server.mjs"],
      "env": {
        "IMA_CLIENT_ID": "你的_client_id",
        "IMA_API_KEY": "你的_api_key"
      }
    }
  }
}

Cline (VS Code)

在 Cline 设置 → MCP Servers → 添加:

{
  "ima": {
    "command": "node",
    "args": ["/path/to/ima-mcp-server/server.mjs"],
    "env": {
      "IMA_CLIENT_ID": "你的_client_id",
      "IMA_API_KEY": "你的_api_key"
    },
    "disabled": false,
    "autoApprove": []
  }
}

VS Code Copilot / Continue

{
  "mcpServers": {
    "ima": {
      "command": "node",
      "args": ["/path/to/ima-mcp-server/server.mjs"],
      "env": {
        "IMA_CLIENT_ID": "你的_client_id",
        "IMA_API_KEY": "你的_api_key"
      }
    }
  }
}

WorkBuddy

编辑 ~/.workbuddy/mcp.json,在 mcpServers 中添加上述 ima 条目,然后在连接器管理页面点击「Trust」启用。

验证

配置完成后,在 agent 软件中尝试:

"列出我的所有知识库"

如果返回知识库列表,说明配置成功。

也可手动测试协议:

node test-protocol.mjs

故障排查

问题

解决方案

未找到 IMA 凭证

检查环境变量或配置文件是否正确设置

IMA API 错误 [xxx]

查看 msg 内容;常见为凭证无效或权限不足

Claude Desktop 未显示工具

重启 Claude Desktop;检查 claude_desktop_config.json 路径与 JSON 格式

Windows 路径需双反斜杠

JSON 中 \\ 表示一个 \,如 C:\\Users\\name\\...

Node 版本不足

升级到 18+,node -v 确认

与 ima-skill 的关系

维度

ima-mcp-server(本项目)

ima-skill(WorkBuddy 内置)

协议

标准 MCP,跨 agent 通用

WorkBuddy skill 格式

适用范围

Claude Desktop、Cursor、Cline 等

仅 WorkBuddy 生态

认证

OpenAPI clientId/apiKey

同(或 WorkBuddy OAuth 连接器)

功能范围

9 个知识库工具(读取 + 笔记正文 + 添加网页 + 上传本地文件)

完整(含文件上传、笔记管理)

传输

stdio

脚本调用

本项目现已补齐本地文件上传(upload_file),功能与 ima-skill 基本对齐;如需笔记的创建/编辑等写操作或 WorkBuddy 免配置 OAuth 连接器,仍可使用 ima-skill;如需在其它 agent 软件中使用标准 MCP,用本项目。

安全说明

  • 凭证仅作为 HTTP 头发送至 ima.qq.com,不发送至任何其它域名

  • 凭证不会被记录到日志或文件

  • import_urls 的 URL 由 IMA 服务端抓取,本地不发送文件内容

  • upload_file 的文件字节仅直传至 IMA 托管的腾讯云 COS(由 create_media 返回的临时凭证授权),不经由任何第三方

License

MIT

Available Tools

9 tools
get_addable_knowledge_base_listA

获取当前用户有权限添加内容的知识库列表。仅在未指定目标知识库时使用。

Inputs: limit, cursor.

get_knowledge_baseA

获取知识库详情(描述、推荐问题等)。支持一次查询 1-20 个知识库。

Inputs: ids (required).

get_knowledge_listA

浏览知识库内容列表(根目录或指定文件夹),分页返回文件与子文件夹。操作根目录时省略 folder_id。folder_id 以 folder_ 前缀开头。

Inputs: knowledge_base_id (required), limit, cursor, folder_id.

get_media_infoA

获取知识库条目的原文内容或下载链接。传入 media_id(来自 get_knowledge_list 或 search_knowledge 的返回)。对微信文章/网页/文件类,返回可访问 URL;对笔记类(media_id 以 note_ 开头),会自动拉取并返回笔记正文(note_content 字段,纯文本)。

Inputs: media_id (required).

get_note_contentA

读取笔记正文(纯文本)。传入 note_id(笔记的数字 ID,即 get_media_info 返回的 notebook_id,或笔记搜索接口返回的 doc_id)。这是读取 IMA 笔记原文的专用接口。

Inputs: note_id (required), target_content_format.

import_urlsA

将网页或微信文章 URL 添加到知识库(1-10 个 URL)。添加到根目录时省略 folder_id。

Inputs: urls (required), knowledge_base_id (required), folder_id.

search_knowledgeA

在指定知识库中按关键词搜索内容(含文件和文件夹),返回命中的标题、摘要片段。这是知识库内容检索的核心接口。

Inputs: query (required), knowledge_base_id (required), cursor.

search_knowledge_baseA

搜索知识库列表。query 传空字符串时返回当前账号下所有可见知识库(含自建与订阅)。知道知识库名称但不知道 ID 时用此接口。

Inputs: limit, query, cursor.

upload_fileA

将本地文件上传到指定知识库(支持 PDF / Word / PPT / Excel / Markdown / 图片 / TXT / XMind / 音频 / HTML 等)。内部流程:类型与大小预检 → 重名检测(命中自动追加时间戳)→ create_media 获取 COS 临时凭证 → 上传 COS → add_knowledge 正式入库。视频文件(.mp4 等)不支持,请改用 import_urls 以 URL 方式添加。verify=true 时仅上传到 COS 不入库,便于验证凭证与网络。

Inputs: file_path (required), knowledge_base_id (required), verify, folder_id.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 9 tools

    Disambiguation4/5

    Most tools have distinct purposes (search vs list vs get, etc.), but get_media_info and get_note_content both handle note retrieval, and search_knowledge_base and get_knowledge_base both deal with KB metadata. Descriptions help clarify which to use, so confusion is limited.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern (get_, search_, import_, upload_). The naming is uniform and predictable, with no mixed casing or irregular verb styles.

    Tool Count5/5

    9 tools is well within the ideal 3-15 range. Each tool serves a clear purpose in the knowledge base workflow, and the set feels neither bloated nor sparse.

    Completeness4/5

    The tool set covers the core workflow well: finding KBs, browsing content, searching, retrieving full content, and adding content via URL or file upload. Missing update/delete operations, but these may be outside the intended scope for this server.

    Related MCP Connectors

    Related MCP Servers