NocoBase CRM MCP
在你的电脑上,让 AI 客户端安全地查询 NocoBase CRM。安装时通过浏览器登录 NocoBase;每位用户使用自己的身份,看到的数据范围与本人在 NocoBase 中的权限一致。
安装
推荐把安装交给支持终端操作的 AI Agent 完成。你不需要克隆源码,也不需要逐条执行安装命令。
安装前准备
- Node.js 20.11 或更高版本;
- 能访问
https://justconn.top; - 你自己的 NocoBase 账号;
- 能读取当前 Gitea 仓库
main分支,并能访问 npm 软件源。
如果 Node.js 尚未安装,安装 Agent 会先说明需要进行的系统变更,并在获得你确认后再继续。
支持 Windows、macOS 和 Linux。三个平台都会安装 main 在任务开始时的最新 Commit;Windows 下载该 Commit 的 .zip,macOS/Linux 下载同一 Commit 的 .tar.gz。
不需要提前创建或复制 Authorize Key。MCP 注册后,Agent 会调用登录工具并把 NocoBase 官方网页链接发给你;桌面环境通常也会自动打开该页面。你在网页中确认授权后,Agent 会自动继续验收。
最快安装方式
把下面整段直接复制给安装 Agent:
请按这个 INSTALL.md 帮我完成 NocoBase CRM MCP 安装。
每次先解析当前 Gitea 仓库 main 分支的最新完整 Commit SHA,并把本次安装固定在该 Commit;不要退回旧 Release。
默认只读;请先注册 MCP,再调用 nocobase_login,把登录链接和确认码发给我,让我只在 NocoBase 官方网页完成授权。
不要向我索要密码、Token 或 Authorize Key,也不要静默安装系统工具。完成前请验证 crm_health 返回 ok=true。
安装协议:
https://git.justconn.top/gitea-admin/nocobase-mcp/raw/branch/main/INSTALL.md
- Agent 会读取 Gitea
main的最新 Commit,把源码快照、安装协议和构建过程固定到同一个 SHA,再在临时目录完成检查和打包。 - Agent 会先注册 MCP,再调用
nocobase_login。桌面环境通常自动打开浏览器;无界面或远程 Agent 会把同一个授权链接和确认码发到当前对话。 - 你在
justconn.top登录、核对确认码并授权后,Agent 会轮询nocobase_login_status,最后确认crm_health返回ok=true。
完整的安装和验收规则见 INSTALL.md。该 main 链接是安装入口;Agent 必须先解析一次最新 Commit,然后重新读取该 Commit 中不可变的同一文件,不能在一次安装中混用不同提交。
重要注意事项
- 只在 NocoBase 网页登录: 安装程序不会读取浏览器 Cookie,也不会接触你的密码;OAuth 令牌只保存到权限受限的个人凭据文件,不会进入聊天、命令参数、环境变量、CRM 配置、MCP 客户端配置或日志。
- 默认只读: 安装后默认只能查询 CRM,不会创建、更新或删除业务数据。
- 权限跟随本人: MCP 不会绕过 NocoBase 的角色、字段权限和行级权限,也不会使用共享管理员账号。
- 只连接公司环境: 程序固定连接
https://justconn.top/api,不会要求你填写其他 NocoBase 地址。 - 始终安装最新提交: 每次安装只解析一次
main的最新 Commit SHA,随后固定该快照完成构建;不会因为旧 Release 可用而安装旧代码。 - 安装在用户目录: 不使用
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。 - 登录失效:让 Agent 调用
nocobase_login并设置force=true,重新在浏览器授权;正常情况下访问令牌会在后台自动刷新。 - 浏览器没有打开:直接打开
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 仓库的读取权限。
更多故障处理和更新、回滚说明见 本机交付与权限验收。
更多文档
- 完整安装协议:供安装 Agent 解析并固定最新 Commit、构建、安装和验收。
- 命令与工具参考:CLI 命令、MCP 工具和可选运行开关。
- 内部架构:模块边界、身份与网络安全设计。
- 本机交付与权限验收:运维、权限验收、更新和回滚。
本地开发
开发者可从源码运行以下检查:
npm ci
npm run check
npm test
npm run build
node dist/index.js --help
本项目要求 Node.js 20.11 或更高版本。安装 Agent 会在临时目录从锁定依赖构建最新 Commit;最终运行包不含额外 npm 运行时依赖,用户不需要长期保留源码开发环境。