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
  1. Agent 会读取 Gitea main 的最新 Commit,把源码快照、安装协议和构建过程固定到同一个 SHA,再在临时目录完成检查和打包。
  2. Agent 会先注册 MCP,再调用 nocobase_login。桌面环境通常自动打开浏览器;无界面或远程 Agent 会把同一个授权链接和确认码发到当前对话。
  3. 你在 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 仓库的读取权限。

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

更多文档

本地开发

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

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

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

S
Description
Local TypeScript MCP for NocoBase CRM using each user's personal Authorize Key
Readme
624 KiB
v0.3.1
Latest
2026-08-15 14:04:55 +08:00
Languages
TypeScript 99.5%
JavaScript 0.5%