Scan to join WeChat groupREADME
🚀 Atomic CRM MCP 服务器
Atomic CRM MCP 服务器是一个用于 Atomic CRM 的 MCP（模型上下文协议）服务器。它能让代理（如 ChatGPT、Claude 等）安全地对 Atomic CRM 实例进行数据读写操作。
- 通过 Supabase 实现 OAuth 2.1 认证
- 添加
query工具，可对 CRM 数据库执行 SQL 查询 - 自动实施行级安全（RLS）
✨ 主要特性
支持的 MCP 客户端
- ChatGPT
- Claude.ai
- Visual Studio Code
- Claude Desktop
- Claude Code
- Cursor
- Goose
- Codex CLI
- Gemini CLI
- ~~Gemini Mobile~~
- ~~ChatGPT Desktop~~
- ~~ChatGPT Mobile~~
📦 安装指南
MCP 服务器设置
-
克隆仓库：
git clone https://github.com/marmelab/atomic-crm-mcp cd your-repo -
安装依赖：
npm install -
添加配置文件
cp .env.example .env
Supabase 设置
-
打开 Supabase 仪表盘
- 访问 https://supabase.com/dashboard 并选择你的项目（或创建一个新项目）
-
启用 OAuth 2.1 服务器
- 进入 认证 → OAuth 服务器
- 点击 启用 Supabase OAuth 服务器
- 将 授权路径 设置为
/#/oauth/consent - 启用 允许动态 OAuth 应用 选项
- 保存更改
-
配置非对称 JWT 签名
- 进入 项目设置 → JWT 密钥
- 在 JWT 签名密钥 选项卡中，如果你看到 开始使用 JWT 签名密钥 的提示，这意味着你当前使用的是旧版 JWT 密钥，点击 迁移 JWT 密钥 按钮
- 如果当前密钥类型为 "Legacy HS256 (共享密钥)"，点击 旋转密钥 以使用新的 "ECC (P256)" 或类似类型的密钥
-
获取 Supabase URL
- 进入 项目设置 → 数据 API
- 找到你的 项目 URL（例如，
https://mrubnlemopavyqvjjwmw.supabase.co） - 将其添加到
.env文件中，作为SUPABASE_URL
-
获取数据库连接字符串
- 进入 项目设置 → 数据库
- 在顶部应用栏中，点击 连接 按钮
- 复制 直接连接 字符串（其中会有
[YOUR-PASSWORD]占位符） - 将其添加到
.env文件中，作为DATABASE_URL - 将
[YOUR-PASSWORD]替换为你的数据库密码。如果你不知道密码，进入 数据库 → 设置 并重置密码。
本地 MCP 服务器
如果你使用 ngrok 等服务，可以在本地运行 MCP 服务器。你需要为 MCP 服务器选择一个可公开访问的 HTTPS URL，例如 https://atomiccrmmcp.ngrok.dev。在下面的说明中，我们将此 URL 称为 MCP_URL。
使用自定义 URL 运行服务器：
npm run dev -- --url=MCP_URL
然后，在另一个终端中使用相同的 URL 启动 ngrok：
ngrok http --url MCP_URL 3000
现在，MCP 服务器可以通过 ngrok URL 访问。
托管 MCP 服务器
将 MCP 服务器部署到你选择的托管提供商。确保在托管提供商的设置中设置 .env 文件中的环境变量。
请注意，主机必须支持 IPV6，因为 Supabase 直接数据库连接不支持 IPV4。这排除了仅支持 IPV4 的提供商，如 Vercel 或 GitHub actions。
将 MCP 服务器添加到 Chat GPT
注意：Atomic CRM MCP 在 ChatGPT 的网页版和移动版上都可以使用。你需要一个付费的 Chat GPT 账户才能使用自定义连接器。
- 在 设置 → 应用 → 高级 设置中启用 开发者模式
- 然后，在 设置 → 应用 下，点击创建按钮
- 按如下方式填写字段：
- 名称：Atomic CRM
- MCP 服务器 URL：（你的 MCP 服务器 URL，例如
MCP_URL/mcp） - 认证方式：OAuth
- 勾选 “我理解并希望继续” 复选框
- 点击 “创建”
- 会打开一个浏览器窗口，让你对 Atomic CRM 进行身份验证并允许 Claude Code 访问。
- 身份验证完成后，你就可以在 Chat GPT 中开始使用 Atomic CRM 扩展。
如果你使用的是工作区或组织账户，需要请求管理员添加并批准自定义连接器，然后才能使用。
将 MCP 服务器添加到 Claude.ai
注意：Atomic CRM MCP 在 Claude 的网页版和移动版上都可以使用。你需要一个付费的 Claude.ai 账户才能使用自定义连接器。
- 打开 Claude.ai 并打开 设置 → 连接器 页面
- 然后点击 “添加自定义连接器”
- 按如下方式填写字段：
- 名称：Atomic CRM
- MCP 服务器 URL：（你的 MCP 服务器 URL，例如
MCP_URL/mcp）
- 点击 “添加”
- 会打开一个浏览器窗口，让你对 Atomic CRM 进行身份验证并允许 Claude Code 访问。
- 身份验证完成后，你就可以在 Chat GPT 中开始使用 Atomic CRM 扩展。
将 MCP 服务器添加到 Visual Studio Code
- 打开命令面板（Ctrl+Shift+P 或 Cmd+Shift+P）并运行 “MCP: 添加服务器...” 命令。
- 在列出 MCP 类型的下拉列表中，选择 “HTTP”
- 提示时输入 MCP 服务器 URL（例如
MCP_URL/mcp）。 - 提示时将此服务器命名为
atomic-crm。 - 根据需要选择 “全局” 或 “本地” 范围。
- 会打开一个对话框，让你对 Atomic CRM 进行身份验证并允许访问。点击 “允许”。
- 会打开一个浏览器窗口，让你对 Atomic CRM 进行身份验证并允许 Claude Code 访问。
- 身份验证完成后，你就可以在 Visual Studio Code 中开始使用 Atomic CRM 扩展。
将 MCP 服务器添加到 Claude Desktop
- 在 Claude Desktop 中导航到设置 > 扩展。
- 点击 “添加自定义扩展”。
- 按如下方式填写字段：
- 名称：Atomic CRM
- URL：（你的 MCP 服务器 URL，例如
MCP_URL/mcp）
- 点击 “添加”。
- 新扩展现在应该出现在你的扩展列表中。点击 “连接” 开始使用。
- 会打开一个浏览器窗口，让你对 Atomic CRM 进行身份验证并允许 Claude 访问。
- 身份验证完成后，你就可以在 Claude 中开始使用 Atomic CRM 扩展。
将 MCP 服务器添加到 Claude Code
-
在终端中运行以下命令，将 Atomic CRM MCP 服务器添加到 Claude Code：
claude mcp add atomic-crm --transport http MCP_URL/mcp -
打开 Claude Code
claude -
列出可用的 MCP 服务器
/mcp -
atomic-crm服务器应显示为 “需要身份验证”。按 Enter 键进行身份验证。 -
会打开一个浏览器窗口，让你对 Atomic CRM 进行身份验证并允许 Claude Code 访问。
-
身份验证完成后，你就可以在 Claude Code 中开始使用 Atomic CRM 扩展。
🔧 技术细节
MCP 工具
get_schema：检索数据库模式，以帮助构建准确的 SQL 查询，包括用于 JOIN 的外键关系。query：对 CRM 数据库执行 SQL 查询，并实施 RLS。支持包括 JOIN 在内的复杂查询。
安全机制
- JWT 验证：所有令牌都根据 Supabase JWKS 进行验证
- RLS 实施：查询使用用户的 JWT 运行，
auth.uid()可在 SQL 中使用 - 会话管理：使用加密安全的会话 ID
- HTTPS 要求：生产环境中必须使用 HTTPS
- 令牌存储：令牌仅保存在内存中，从不记录
OAuth 流程
- MCP 客户端在未进行身份验证的情况下连接 → 服务器返回 401 并附带受保护资源元数据 URL
- 客户端从受保护资源元数据中发现 OAuth 端点
- 客户端获取 Supabase 的 OpenID Connect 配置
- 用户通过 Supabase（你的 Atomic CRM 身份验证界面）进行身份验证
- 客户端接收 JWT 访问令牌
- 客户端使用承载令牌进行经过身份验证的 MCP 请求
- 服务器根据 Supabase JWKS 验证 JWT
- 服务器使用用户的 JWT 执行查询以实施 RLS
📚 详细文档
故障排除
MCP 服务器连接失败
- 确保 Supabase 使用 JWT 签名密钥（RS256）而不是 JWT 签名密钥（HS256） （进入 Supabase 仪表盘 > 设置 > JWT 密钥） 当前密钥不应使用 “Legagy HS256 (共享密钥)” 类型，而应使用 “ECC (P256)” 等类型。
JWT 验证失败
- 验证 Supabase 是否配置为非对称 JWT 签名（RS256）
- 检查
SUPABASE_URL是否与令牌的iss声明匹配 - 确保在 Supabase 仪表盘中启用了 OAuth 2.1
数据库连接失败
- “未找到租户或用户”：你的连接字符串格式不正确。对于直接连接，使用：
postgresql://postgres:PASSWORD@db.PROJECT-REF.supabase.co:5432/postgres- 不要使用带有
postgres.PROJECT-REF或端口 6543 的池化器格式
- 验证
DATABASE_URL是否正确且可访问 - 确保你已将
[YOUR-PASSWORD]替换为实际的数据库密码 - 检查防火墙规则是否允许从你的服务器进行连接
RLS 阻止查询
- 检查 RLS 策略是否允许经过身份验证的用户访问
- 验证
auth.uid()是否与预期的用户 ID 匹配 - 使用服务角色密钥进行测试以绕过 RLS（仅用于开发）
贡献代码
## 在开发模式下运行
npm run dev
## 为生产环境构建
npm run build
npm start
## 类型检查
npm run typecheck
参考资料
📄 许可证
ISC