Atomic Crm MCP

🚀 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 服务器设置

1. 克隆仓库：

   git clone https://github.com/marmelab/atomic-crm-mcp
   cd your-repo
   

2. 安装依赖：

   npm install
   

3. 添加配置文件

   cp .env.example .env
   

Supabase 设置

1. 打开 Supabase 仪表盘

   • 访问 https://supabase.com/dashboard 并选择你的项目（或创建一个新项目）

2. 启用 OAuth 2.1 服务器

   • 进入 认证 → OAuth 服务器
   • 点击 启用 Supabase OAuth 服务器
   • 将 授权路径 设置为 /#/oauth/consent
   • 启用 允许动态 OAuth 应用 选项
   • 保存更改

3. 配置非对称 JWT 签名

   • 进入 项目设置 → JWT 密钥
   • 在 JWT 签名密钥 选项卡中，如果你看到 开始使用 JWT 签名密钥 的提示，这意味着你当前使用的是旧版 JWT 密钥，点击 迁移 JWT 密钥 按钮
   • 如果当前密钥类型为 "Legacy HS256 (共享密钥)"，点击 旋转密钥 以使用新的 "ECC (P256)" 或类似类型的密钥

4. 获取 Supabase URL

   • 进入 项目设置 → 数据 API
   • 找到你的 项目 URL（例如，https://mrubnlemopavyqvjjwmw.supabase.co）
   • 将其添加到 .env 文件中，作为 SUPABASE_URL

5. 获取数据库连接字符串

   • 进入 项目设置 → 数据库
   • 在顶部应用栏中，点击 连接 按钮
   • 复制 直接连接 字符串（其中会有 [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 账户才能使用自定义连接器。

1. 在 设置 → 应用 → 高级 设置中启用 开发者模式
2. 然后，在 设置 → 应用 下，点击创建按钮
3. 按如下方式填写字段：
   • 名称：Atomic CRM
   • MCP 服务器 URL：（你的 MCP 服务器 URL，例如 MCP_URL/mcp）
   • 认证方式：OAuth
   • 勾选 “我理解并希望继续” 复选框
4. 点击 “创建”
5. 会打开一个浏览器窗口，让你对 Atomic CRM 进行身份验证并允许 Claude Code 访问。
6. 身份验证完成后，你就可以在 Chat GPT 中开始使用 Atomic CRM 扩展。

如果你使用的是工作区或组织账户，需要请求管理员添加并批准自定义连接器，然后才能使用。

将 MCP 服务器添加到 Claude.ai

注意：Atomic CRM MCP 在 Claude 的网页版和移动版上都可以使用。你需要一个付费的 Claude.ai 账户才能使用自定义连接器。

1. 打开 Claude.ai 并打开 设置 → 连接器 页面
2. 然后点击 “添加自定义连接器”
3. 按如下方式填写字段：
   • 名称：Atomic CRM
   • MCP 服务器 URL：（你的 MCP 服务器 URL，例如 MCP_URL/mcp）
4. 点击 “添加”
5. 会打开一个浏览器窗口，让你对 Atomic CRM 进行身份验证并允许 Claude Code 访问。
6. 身份验证完成后，你就可以在 Chat GPT 中开始使用 Atomic CRM 扩展。

将 MCP 服务器添加到 Visual Studio Code

1. 打开命令面板（Ctrl+Shift+P 或 Cmd+Shift+P）并运行 “MCP: 添加服务器...” 命令。
2. 在列出 MCP 类型的下拉列表中，选择 “HTTP”
3. 提示时输入 MCP 服务器 URL（例如 MCP_URL/mcp）。
4. 提示时将此服务器命名为 atomic-crm。
5. 根据需要选择 “全局” 或 “本地” 范围。
6. 会打开一个对话框，让你对 Atomic CRM 进行身份验证并允许访问。点击 “允许”。
7. 会打开一个浏览器窗口，让你对 Atomic CRM 进行身份验证并允许 Claude Code 访问。
8. 身份验证完成后，你就可以在 Visual Studio Code 中开始使用 Atomic CRM 扩展。

将 MCP 服务器添加到 Claude Desktop

1. 在 Claude Desktop 中导航到设置 > 扩展。
2. 点击 “添加自定义扩展”。
3. 按如下方式填写字段：
   • 名称：Atomic CRM
   • URL：（你的 MCP 服务器 URL，例如 MCP_URL/mcp）
4. 点击 “添加”。
5. 新扩展现在应该出现在你的扩展列表中。点击 “连接” 开始使用。
6. 会打开一个浏览器窗口，让你对 Atomic CRM 进行身份验证并允许 Claude 访问。
7. 身份验证完成后，你就可以在 Claude 中开始使用 Atomic CRM 扩展。

将 MCP 服务器添加到 Claude Code

1. 在终端中运行以下命令，将 Atomic CRM MCP 服务器添加到 Claude Code：

   claude mcp add atomic-crm --transport http MCP_URL/mcp
   

2. 打开 Claude Code

   claude
   

3. 列出可用的 MCP 服务器

   /mcp
   

4. atomic-crm 服务器应显示为 “需要身份验证”。按 Enter 键进行身份验证。

5. 会打开一个浏览器窗口，让你对 Atomic CRM 进行身份验证并允许 Claude Code 访问。

6. 身份验证完成后，你就可以在 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 流程

1. MCP 客户端在未进行身份验证的情况下连接 → 服务器返回 401 并附带受保护资源元数据 URL
2. 客户端从受保护资源元数据中发现 OAuth 端点
3. 客户端获取 Supabase 的 OpenID Connect 配置
4. 用户通过 Supabase（你的 Atomic CRM 身份验证界面）进行身份验证
5. 客户端接收 JWT 访问令牌
6. 客户端使用承载令牌进行经过身份验证的 MCP 请求
7. 服务器根据 Supabase JWKS 验证 JWT
8. 服务器使用用户的 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

参考资料

• MCP 规范
• MCP 授权
• Supabase OAuth 服务器
• RFC 9728 - OAuth 受保护资源元数据

📄 许可证

ISC