ima-mcp-server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@ima-mcp-server 列出我的所有知识库"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
ima-mcp-server
将 IMA 知识库 官方 OpenAPI 封装为标准 MCP(Model Context Protocol) 服务器,可在任何支持 MCP 的 agent 软件中检索、浏览、读取知识库内容。
特性
✅ 标准 MCP 协议(stdio 传输),兼容所有 MCP 客户端
✅ 9 个知识库工具:搜索、浏览、读取原文、读取笔记正文、添加网页、上传本地文件
✅ 凭证灵活配置(环境变量 / 配置文件)
✅ 零外部服务依赖,纯 Node.js 运行
Related MCP server: agentdocs-mcp
可用工具
工具 | 功能 |
| 搜索知识库列表(空 query 返回全部,含订阅库) |
| 获取知识库详情(描述、推荐问题) |
| 浏览知识库内容(根目录/文件夹,分页) |
| 在知识库内按关键词搜索文档 |
| 获取条目原文/下载链接;笔记类自动返回正文( |
| 读取笔记正文(纯文本),传入 note_id |
| 获取可添加内容的知识库列表 |
| 将网页/微信文章添加到知识库 |
| 上传本地文件到知识库(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。
前置要求
Node.js ≥ 18(内置 fetch)
IMA OpenAPI 凭证:在 https://ima.qq.com/agent-interface 获取 Client ID 和 API Key
安装
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 服务器):
git clone https://github.com/rowanlin-dev/ima-mcp-server.git ima-mcp-server后npm install;把 IMA 的 Client ID / API Key 写入
~/.config/ima/client_id和~/.config/ima/api_key,权限设 600;在我的 MCP 客户端(Claude Desktop / Cursor / Cline / WorkBuddy 等)配置里加一个
imaserver:command: node,args: ["<绝对路径>/ima-mcp-server/server.mjs"];跑
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.jsonmacOS:
~/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故障排查
问题 | 解决方案 |
| 检查环境变量或配置文件是否正确设置 |
| 查看 msg 内容;常见为凭证无效或权限不足 |
Claude Desktop 未显示工具 | 重启 Claude Desktop;检查 |
Windows 路径需双反斜杠 | JSON 中 |
Node 版本不足 | 升级到 18+, |
与 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 toolsget_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
Scored across 9 tools
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.
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.
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.
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
Search and manage your team's knowledge from MCP clients.
Knowledge base MCP for AI agents on iknow.dev. Search, read, and maintain via OAuth.
Make your knowledge agent-ready. One MCP endpoint, 5 connectors, 3 search modes.
Authenticated MCP access to the AIKI open knowledge commons.
Related MCP Servers
FlicenseNot gradedqualityCmaintenanceEnables AI clients to interact with eGain Knowledge, supporting portal browsing, article reading, knowledge search, and AI-powered answers through MCP.1-- AlicenseAqualityBmaintenanceEnables MCP clients to read, search, create, update, and share collaborative documentation pages on the AgentDocs platform.251,007 npm1MIT
- AlicenseBqualityDmaintenanceEnables interaction with the Innovaas Knowledge Management System through MCP, providing multi-modal search, RAG-powered chat with intelligent token management, and document access.7MIT
- AlicenseNot gradedqualityFmaintenancePrivate knowledge base with Markdown pages and assets, exposed via MCP for agent access.2MIT