NocoBase CRM MCP

在你的电脑上，让 AI 客户端安全地查询 NocoBase CRM。首次需要认证时通过浏览器登录 NocoBase；每位用户使用自己的身份，看到的数据范围与本人在 NocoBase 中的权限一致。

安装或更新

推荐把首次安装和后续更新都交给支持终端操作的 AI Agent 完成。同一段提示可以重复使用：Agent 会先检查本机状态，未安装时完成首次安装，已安装时保留个人配置和登录状态并更新到最新 Commit。你不需要克隆源码，也不需要逐条执行命令。

安装前准备

Node.js 20.11 或更高版本；
能访问 https://justconn.top；
你自己的 NocoBase 账号；
能读取当前 Gitea 仓库 main 分支，并能访问 npm 软件源。

如果 Node.js 尚未安装，Agent 会先说明需要进行的系统变更，并在获得你确认后再继续。

支持 Windows、macOS 和 Linux，三个平台都会使用任务开始时 main 的最新 Commit。

不需要提前创建或复制 Authorize Key。MCP 注册或重载后，Agent 会先检查现有登录；只有确实需要认证时才调用登录工具并把 NocoBase 官方网页链接发给你。桌面环境通常也会自动打开该页面，你确认授权后 Agent 会自动继续验收。

最快方式

无论是第一次安装还是以后更新，都把下面整段直接复制给 Agent：

请按以下 INSTALL.md 帮我安装或更新 NocoBase CRM MCP。自动判断首次安装、更新、修复或已是最新，使用 main 当前最新 Commit，并严格执行文档中的安全与验收规则；已有安装时保留配置、凭据和读写模式。只有确实需要登录时，才把 NocoBase 官方网页链接和确认码发给我。无界面或远程环境也要发到当前私聊；它们不是密码、Token、Key 或 device_code，不要要求远程桌面。安装系统工具前先征得我同意。完成前确认 crm_health 返回 ok=true。
https://git.justconn.top/gitea-admin/nocobase-mcp/raw/branch/main/INSTALL.md

Agent 会固定任务开始时的最新 Commit，按本机状态执行安装、更新、修复或直接验收；已有安装会保留个人状态，相同 Commit 不会重复构建。注册后先检查 crm_health，只有认证确实缺失或失效时才发起登录。桌面环境通常自动打开浏览器；远程 Agent 会把同一授权链接发到当前对话，MCP 重启后也能继续该授权。

完整的安装、更新和验收规则见 INSTALL.md。该 main 链接是统一入口；Agent 必须先解析一次最新 Commit，然后重新读取该 Commit 中不可变的同一文件，不能在一次任务中混用不同提交。

重要注意事项

只在 NocoBase 网页登录： 安装程序不会读取浏览器 Cookie，也不会接触你的密码；OAuth 令牌只保存到权限受限的个人凭据文件，不会进入聊天、命令参数、环境变量、CRM 配置、MCP 客户端配置或日志。
默认只读： 安装后默认只能查询 CRM，不会创建、更新或删除业务数据。
权限跟随本人： MCP 不会绕过 NocoBase 的角色、字段权限和行级权限，也不会使用共享管理员账号。
远程登录不需要远程桌面： Hermes Agent、OpenClaw 或无界面服务器会把短期 OAuth Device Flow 验证链接和确认码发到发起用户的当前私聊；它们不能发到群聊、公开频道或第三方，但不是密码、Token、Key 或内部 device_code。
只连接公司环境： 程序固定连接 https://justconn.top/api，不会要求你填写其他 NocoBase 地址。
始终使用最新提交： 每次安装或更新只解析一次 main 的最新 Commit SHA，随后固定该快照完成任务；不会因为旧 Release 可用而安装旧代码。
更新保留个人状态： 更新不会覆盖 CRM config.json、OAuth 凭据或现有只读/写入模式；已有登录有效时不会要求重新授权。
安装在用户目录： 不使用 sudo，不会全局安装本项目，也不需要 Git、Python、uv 或 nb CLI。源码和构建依赖只存在于临时目录，安装后仅保留打包运行文件。
受限仓库需要授权： 如果 Agent 无法读取 Gitea main 或对应 Commit 快照，请联系仓库管理员开通权限，不要把访问令牌发到聊天中。

安装后可以做什么

你可以直接让 AI：

查询客户、联系人和跟进记录；
按负责人、团队、状态或时间范围筛选 CRM 数据；
查看 CRM 总览、团队贡献和长期未跟进客户；
查看项目详情和项目跟进时间线。

例如：

列出我负责的、最近 30 天没有有效跟进的客户。

查看“华东团队”本月的客户、跟进和在途项目概况。

可选写入

只有在你明确需要创建或更新项目，并且管理员已经确认你的 NocoBase 权限时，才应启用写入模式。

写入模式只增加固定字段的项目创建和更新能力，不提供删除操作，也不开放任意集合或任意字段写入。不要为了绕过权限错误而换用共享高权限 Key。

遇到问题

尚未登录：让 Agent 调用 nocobase_login，把返回的 login_url 和 user_code 发给你；授权后调用 nocobase_login_status。
只想检查更新：仍发送上面的统一提示；如果本机已经是 main 当前最新 Commit，Agent 会直接验证并报告“已是最新”，不重复构建或登录。
登录失效：让 Agent 调用 nocobase_login 并设置 force=true，重新在浏览器授权；正常情况下访问令牌会在后台自动刷新。
浏览器没有打开：让 Agent 把 nocobase_login 返回的 justconn.top 链接和确认码发到当前私聊，然后在你的手机或电脑浏览器打开；不需要服务器远程桌面。若当前是群聊，请先转到与 Agent 的一对一私聊。
MCP 客户端暂时无法调用登录工具：可在本人终端运行安装程序的 setup --no-browser，这是备用入口。
仅在 OAuth 暂时不可用且管理员明确要求时，才使用 setup --manual-key 的隐藏输入备用模式；不要把 Key 发到聊天中。
返回 NO_PERMISSIONS：请检查本人 NocoBase 角色和数据权限。
请求超时：确认可以访问 https://justconn.top，或缩小查询范围。
最新 Commit 无法解析或构建失败：停止本次任务并报告 Commit SHA 和失败步骤，不要退回旧 Release。
源码快照无法下载：确认当前账号或 Agent 已获得 Gitea 仓库的读取权限。

更多故障处理和更新、回滚说明见本机交付与权限验收。

本地开发

开发者可从源码运行以下检查：

npm ci
npm run check
npm test
npm run build
node dist/index.js --help

本项目要求 Node.js 20.11 或更高版本。需要安装或更新时，Agent 会在临时目录从锁定依赖构建最新 Commit；最终运行包不含额外 npm 运行时依赖，用户不需要长期保留源码开发环境。

7.4 KiB Raw Permalink Blame History Unescape Escape