金大哥 - atomic-crm-mcp MCP 详情

article

README

🚀 Atomic CRM MCP 服务器

Atomic CRM MCP 服务器是一个用于 Atomic CRM 的 MCP（模型上下文协议）服务器。它能让代理（如 ChatGPT、Claude 等）安全地对 Atomic CRM 实例进行数据读写操作。

./assets/screenshot.png

通过 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

atomic-crm-mcp