Atomic Crm MCP

🚀 Atomic CRM MCP Server

Atomic CRM 用のMCP（Model Context Protocol）サーバーです。エージェント（例：ChatGPT、Claudeなど）がAtomic CRMインスタンスに対してデータの読み書きを安全に行えるようにします。

• SupabaseによるOAuth 2.1認証
• CRMデータベースに対してSQLを実行する query ツールを追加
• 自動的に行レベルセキュリティ（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 (Shared Secret)" タイプの場合、キーをローテートする をクリックして、"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 ファイルの環境変数をホスティングプロバイダーの設定に設定することを確認してください。

Supabaseの直接データベース接続はIPv4をサポートしていないため、ホストはIPv6をサポートする必要があります。これにより、VercelやGitHubアクションなどのIPv4のみをサポートするプロバイダーは除外されます。

Chat GPTにMCPサーバーを追加する

注意：Atomic CRM MCPは、ChatGPTのWeb版とモバイル版の両方で動作します。カスタムコネクタを使用するには、有料の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拡張機能を使用できます

ワークスペースまたは組織アカウントを使用している場合は、使用する前に管理者にカスタムコネクタを追加して承認してもらう必要があります。

Claude.aiにMCPサーバーを追加する

注意：Atomic CRM MCPは、ClaudeのWeb版とモバイル版の両方で動作します。カスタムコネクタを使用するには、有料の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拡張機能を使用できます

Visual Studio CodeにMCPサーバーを追加する

1. コマンドパレット（Ctrl+Shift+PまたはCmd+Shift+P）を開き、「MCP: Add Server...」コマンドを実行します
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拡張機能を使用できます

Claude DesktopにMCPサーバーを追加する

1. Claude Desktopで、設定 > 拡張機能に移動します
2. 「カスタム拡張機能を追加」をクリックします
3. 以下のようにフィールドを入力します：
   • 名前：Atomic CRM
   • URL：（あなたのMCPサーバーURL、例：MCP_URL/mcp）
4. 「追加」をクリックします
5. 新しい拡張機能が拡張機能のリストに表示されます。「接続」をクリックして使用を開始します
6. ブラウザウィンドウが開き、Atomic CRMに認証し、Claudeへのアクセスを許可します
7. 認証が完了すると、ClaudeでAtomic CRM拡張機能を使用できます

Claude CodeにMCPサーバーを追加する

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：RLSを適用してCRMデータベースに対してSQLクエリを実行します。JOINを含む複雑なクエリもサポートします。

セキュリティ

• JWT検証：すべてのトークンはSupabaseのJWKSに対して検証されます
• RLS適用：クエリはユーザーのJWTで実行され、SQLで auth.uid() が使用可能です
• セッション管理：暗号学的に安全なセッションID
• HTTPS必須：本番環境ではHTTPSを使用する必要があります
• トークン保管：トークンはメモリ内にのみ保持され、ログに記録されることはありません

OAuthフロー

1. MCPクライアントが認証なしで接続する → サーバーは401を返し、保護されたリソースメタデータURLを含む
2. クライアントは保護されたリソースメタデータからOAuthエンドポイントを検出する
3. クライアントはSupabaseのOpenID Connect構成を取得する
4. ユーザーはSupabase（Atomic CRMの認証UI）を介して認証する
5. クライアントはJWTアクセストークンを受け取る
6. クライアントはベアラートークンを使用して認証済みのMCPリクエストを行う
7. サーバーはSupabaseのJWKSに対してJWTを検証する
8. サーバーはユーザーのJWTを使用してクエリを実行し、RLSを適用する

📚 トラブルシューティング

MCPサーバーへの接続が失敗する

• SupabaseがJWT署名キー（RS256）を使用していることを確認してください （Supabaseダッシュボード > 設定 > JWTキーに移動します） 現在のキーは "Legagy HS256 (Shared Secret)" タイプではなく、"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 Protected Resource Metadata

📄 ライセンス

ISC