suitecrm-mcp

suitecrm-mcp

⚡ AI エージェントをエンタープライズ CRM に 5 分以内に安全に接続できます。本番環境に対応しています。

SuiteCRM 用のオープンソース MCP（Model Context Protocol）ゲートウェイです。Claude Desktop、Claude Code、OpenClaw などの AI アシスタントが、安全で永続的な SSE 接続を介して CRM データを読み書きできます。

実際の本番環境への導入をもとに構築されています。商用の代替製品は高価ですが、これは無料でオープンソースです。

水平スケーリングを実現する Redis ベースのステートレスアーキテクチャに加え、Prometheus メトリクス、Grafana ダッシュボード（33 パネル）、Loki ログ集約を含む包括的なオブザーバビリティスタックを備えています。

🚀 SuiteCRM-MCP が選ばれる理由

🛡️ エンタープライズ向けの信頼性とセキュリティ

データの完全性とプライバシーが絶対条件となる本番環境向けに構築されています。

• 認証情報に対するゼロトラスト： CRM のパスワードがゲートウェイサーバーの外部に出ることはありません。MCP クライアント（Claude など）が保持するのは、失効可能な不透明な API キーのみです。
• アイデンティティを最優先： Auth0、Azure AD、または任意の OIDC プロバイダーとシームレスに統合できます。
• 監査に対応： すべてのツール呼び出しが構造化 JSON（Loki）で記録されるため、AI エージェントが実行している内容をリアルタイムで正確に確認できます。
• サーキットブレーカーによる保護： バックエンドが応答しなくなった場合に、CRM を連鎖障害から自動的に保護します。

目次

✨ 機能

• 24 個のツールで、完全な CRUD、アクティビティの記録（通話、タスク、メモ）、一括操作、ファイル添付、ドロップダウンの調査などに対応
• SSE トランスポート - Claude Desktop、Claude Code、OpenClaw、および HTTP+SSE に対応するあらゆる MCP クライアントと互換性があります
• OAuth2/OIDC 認証 - ユーザーは Auth0、Azure AD、または任意の OIDC プロバイダーを通じてログインし、ゲートウェイが個人用の取り消し可能な API キーを発行します
• クライアントマシンに認証情報を保存しません - MCP クライアントが保持するのは不透明な API キーのみです。CRM のパスワードはゲートウェイに保存されます
• グループベースのエンティティアクセス - JWT のグループクレームによって、各ユーザーがアクセスできる CRM インスタンスを制限します
• セッションの自動更新 - 期限切れの CRM セッションは、透過的に再認証されます
• ステートレスでスケーラブル - 認証セッションとプロファイルは Redis にキャッシュされるため、ゼロダウンタイムでの再起動と、スティッキーセッションルーティングによるロードバランサー配下での水平スケーリングが可能です（SSE 接続はプロセスごとです。/messages エンドポイントは、SSE トランスポートを所有する同じプロセスに到達する必要があります）
• 統合インストーラー - 1 つのスクリプトで、単一の CRM（nginx なし）にも、nginx 配下の N 個の CRM にも対応し、OAuth の対話型セットアップも行います
• エンティティプレフィックス付きツール - 複数の CRM インスタンスを名前の衝突なく並行して実行できます
• 管理者向けレポート - mcp-admin report は Loki と SQLite から閲覧可能な HTML アクティビティレポートを生成します。ユーザーごとの詳細表示では、呼び出し履歴、ドライラン、モジュールとフィールドの詳細を含むエラーを確認できます

↑ ページの先頭に戻る

🛠️ ツール

{prefix} を設定済みの SUITECRM_PREFIX に置き換えてください（デフォルト：suitecrm）。

対応モジュールには、Accounts、Contacts、Leads、Opportunities、Cases、Calls、Meetings、Tasks、Notes、Emails、Documents、Campaigns、AOS_Quotes、AOS_Invoices、AOS_Products、AOS_Contracts、AOR_Reports、AOW_WorkFlow、SecurityGroups、およびインスタンス内のすべてのカスタムモジュールが含まれます。

↑ ページの先頭に戻る

🏗️ アーキテクチャ

%%{init: {"flowchart": {"curve": "linear"}}}%%
flowchart TB
    IdP["🔐 Auth0 / Azure AD\nIdentity Provider"]

    subgraph Clients["MCP Clients"]
        CD["Claude Desktop"] ~~~ CC["Claude Code"] ~~~ OC["OpenClaw"]
    end

    GW["⚡ suitecrm-mcp gateway\nOAuth2 · API keys · SSE"]

    subgraph CRMs["SuiteCRM Instances"]
        C1[("CRM A")] ~~~ C2[("CRM B")] ~~~ CX[("CRM X")]
    end

    IdP -.->|"confirms identity (OAuth2 callback)"| GW
    GW -.->|"issues API key"| Clients
    Clients -->|"Bearer token"| GW
    GW -->|"Hybrid v8 GraphQL\n(v4_1 Fallback)"| CRMs

    style GW fill:#2b6cb0,stroke:#63b3ed,stroke-width:2px,color:#fff
    style IdP fill:#2d3748,stroke:#718096,color:#e2e8f0
    style CD fill:#2a4a7f,stroke:#63b3ed,stroke-width:1px,color:#ebf8ff
    style CC fill:#2a4a7f,stroke:#63b3ed,stroke-width:1px,color:#ebf8ff
    style OC fill:#2a4a7f,stroke:#63b3ed,stroke-width:1px,color:#ebf8ff
    style C1 fill:#553c9a,stroke:#b794f4,stroke-width:1px,color:#faf5ff
    style C2 fill:#553c9a,stroke:#b794f4,stroke-width:1px,color:#faf5ff
    style CX fill:#553c9a,stroke:#b794f4,stroke-width:1px,color:#faf5ff
    style Clients fill:#0d1b2e,stroke:#4299e1,stroke-width:1px,color:#90cdf4
    style CRMs fill:#1a0533,stroke:#9f7aea,stroke-width:1px,color:#d6bcfa

ユーザーは Auth0 または Azure AD を通じて一度ログインすると、ゲートウェイから個人用 API キーが発行されます。MCP クライアントは、すべてのリクエストに Authorization: Bearer <key> としてこのキーを付与します。CRM の認証情報がゲートウェイの外に出ることはありません。複数の CRM インスタンスに対応しており、それぞれに専用のポートとツール名前空間（suitecrm_crm1_*、suitecrm_crm2_*）が割り当てられます。

スマートハイブリッドルーティング： ゲートウェイは、基本的な CRUD 操作とレコードの取得を、超高速な SuiteCRM 8 GraphQL API 経由で自動的にルーティングします。AI が GraphQL でサポートされていない生 SQL フィルターを必要とする複雑な検索を要求した場合、ゲートウェイがリクエストをインターセプトし、レガシー v4.1 REST API に自動的にフェイルオーバーするため、手動操作なしで完全な機能互換性を実現します。

ステートレスな永続化： 認証セッションとユーザープロファイルをローカルメモリやファイルから Redis に移すことで、ゲートウェイは完全にステートレスになります。これにより、水平スケーリング（ロードバランサーの背後で複数のゲートウェイインスタンスを実行）、グローバルなレート制限、アクティブな AI 接続を切断しないシームレスな再起動が可能になります。ロードバランサーの背後で複数のインスタンスを実行する場合は、スティッキーセッションルーティングが必要です。SSE トランスポートとその /messages エンドポイントは、同じプロセスに到達する必要があります。

↑ トップに戻る

📊 オブザーバビリティ

docker-compose.yml で完全なオブザーバビリティスタックを提供しており、コマンドを 1 つ実行するだけで、ゲートウェイとともにすべてが起動します。

サーキットブレーカーのオープン、高い認証失敗率、レイテンシー SLO の違反、セッションの大量失効に関するアラートルールが含まれています。

mcp-admin report は、両方のソースから HTML アクティビティレポートを生成します。Loki が過去の呼び出しを提供し、SQLite が現在の期間をカバーして、両者は自動的に統合されます。既定の期間は日次です。--period weekly と --period monthly も指定できます。--serve を指定すると、nginx 経由でレポートを /report に公開します。--user <email> を指定すると、単一ユーザーの呼び出し、ドライラン、エラーをモジュールやフィールドの詳細まで掘り下げて確認できます。

↑ トップに戻る

📋 前提条件

• Ubuntu 20.04+ または Debian 11+（インストーラーは apt、systemd、nginx を使用します）
• Python 3.8+
• root／sudo アクセス
• Node.js がインストールされていない場合は自動的にインストールされます
• Redis 6.0+（セッションとプロファイルの永続化に必要）

↑ トップに戻る

🔑 SuiteCRM API ユーザーの設定

接続する前に、CRM ユーザーの API アクセスが有効になっていることを確認してください。

1. 管理者として SuiteCRM にログインします
2. 管理 → ユーザー管理 に移動し、認証に使用するユーザーを開きます
3. 「Is Admin」 にチェックを入れるか、「API User」 を Yes に設定します（フィールド名は SuiteCRM のバージョンによって異なります）
4. 保存します

API アクセスが有効になっていない場合、接続時にゲートウェイから CRM authentication failed: Invalid Login という HTTP 401 エラーが直ちに返されます。これは初回実行時に最もよくある失敗です。

本番環境では、AI アシスタントに必要なモジュール権限だけを持つ専用の API ユーザーを作成してください。管理者アカウントは使用しないでください。

↑ トップに戻る

⚡ クイックスタート - 単一の CRM

HTTPS と OAuth ログインを自動で設定して、1 つの CRM を使用します。

要件： Ubuntu/Debian、Python 3.8 以上、root アクセス、このサーバーを指すドメイン、OAuth アプリの認証情報（docs/auth0-setup.mdを参照）

git clone https://github.com/anirudhx7/suitecrm-mcp.git
cd suitecrm-mcp
sudo python3 install.py \
  --url https://your-crm.example.com \
  --domain mcp.yourserver.com \
  --email [email protected]

インストーラーで OAuth の設定（issuer、client ID/secret、audience、gateway URL）の入力を求められた後、nginx、certbot、systemd が自動的に設定されます。

インストール後、ユーザーは https://mcp.yourserver.com/auth/login で認証し、API キーを取得します。

ゲートウェイの稼働状況をテストする：

curl https://mcp.yourserver.com/health

Claude Desktop で動作を確認する：

MCP サーバーの設定を追加（docs/connect-claude-desktop.mdを参照）して Claude Desktop を再起動した後、ハンマーのアイコンをクリックします。suitecrm_search、suitecrm_get など、24 個のツールが表示されます。

テスト用のプロンプトを試してください：「"List the first 5 accounts in the CRM"」。Claude が自動的に suitecrm_search を呼び出します。

↑ トップに戻る

🌐 複数エンティティのインストール

nginx の背後に N 個の CRM インスタンスを配置します。それぞれに独自のポートとパスが割り当てられます。

1. 設定をコピーして入力します：

cp entities.example.json entities.json
# Edit entities.json with your CRM endpoints and ports

2. インストーラーを実行します：

sudo python3 install.py --config entities.json

3. HTTPS を有効にします（本番環境では推奨）：

--domain と --email を渡します。インストーラーが nginx の設定をドメインに合わせて更新し、certbot を自動的に実行します。

sudo python3 install.py --config entities.json \
  --domain mcp.yourserver.com \
  --email [email protected]

ドメインはあらかじめこのサーバーのパブリック IP を指している必要があり、ポート 80 と 443 が開放されている必要があります。この手順の後、ゲートウェイは https://mcp.yourserver.com/<code>/sse で利用できます。

設定が完了すると、ドメインは自動的に保存されます。以降の --add と --remove の実行では、再度 --domain を指定しなくても HTTPS が維持されます。

4. nginx のポートを開放します（ufw を使用している場合。HTTP のみのインストールで必要です）：

sudo ufw allow 8080/tcp

5. 特定のエンティティをテストします： /auth/login で認証し、API キーを取得した後：

curl -s -H "Authorization: Bearer your_api_key_here" \
  http://YOUR_SERVER:8080/crm1/test
# Expected: {"success":true,"crm_user":"...","email":"...","entity":"crm1"}

6. 接続先： http://YOUR_SERVER:8080/<code>/sse（または HTTPS が有効な場合は https://your-domain/<code>/sse）

Claude Desktop で動作を確認する： Claude Desktop を再起動した後、ハンマーのアイコンをクリックします。エンティティごとに 24 個のツールが表示されます。例：suitecrm_crm1_search、suitecrm_crm2_search など。

後からエンティティを追加する（既存のエンティティは停止しません）：

sudo python3 install.py --add --config entities.json

エンティティを削除する：

sudo python3 install.py --remove crm2

↑ トップに戻る

🐳 Docker

Node.js やシステムパッケージに手を加えずにゲートウェイを実行する最速の方法です。main へのプッシュごとに、ビルド済みイメージが GitHub Container Registry に公開されます。

本番環境では、latest を固定せずに使うのではなく、v5.4.0 などのリリースタグを指定してください。

curl -o docker-compose.yml https://raw.githubusercontent.com/anirudhx7/suitecrm-mcp/v5.4.0/docker-compose.yml

エンティティの設定を作成します（認証サービスはこれを読み込んで、MCP クライアントのコマンドを構築します）：

cp entities.example.json entities.json
# edit entities.json - set endpoint, port, group for your CRM

docker-compose.yml を編集し、SUITECRM_ENDPOINT、AUTH0_* 変数、GATEWAY_PUBLIC_URL を設定してから、次を実行します：

docker compose up -d

ゲートウェイは http://localhost:3101 で実行されます。/auth/login にアクセスして認証し、API キーを取得してください。

固定したリリースを新しいバージョンに更新するには、docker-compose.yml のイメージタグを変更して再デプロイします：

docker compose pull && docker compose up -d

v5.0.0 より前のバージョンからアップグレードする場合： v5.0.0 ではステートレスな Redis アーキテクチャが導入されました。古いイメージで作成された suitecrm-state という名前の既存ボリュームがある場合、SQLite 用には使用されなくなります。新しい Redis コンテナとボリュームが自動的にプロビジョニングされます。

docker compose down
docker volume rm suitecrm-mcp_suitecrm-state
docker compose up -d

すべての永続状態（セッション、プロファイル）はこのボリュームに保存されます。再作成するとこれらのファイルが消去されるため、ユーザーは再度ログインする必要があります。

自己署名 CRM 証明書を使用する場合は、環境変数ブロックに NODE_TLS_REJECT_UNAUTHORIZED: "0" を追加してください。HTTPS を終端するには（本番環境で OAuth を使用する場合に必須です）、リバースプロキシ（nginx、Caddy）を前段に配置します。

ゲートウェイの稼働状況をテストする：

curl http://localhost:3101/health

Docker を使用した複数エンティティ構成

各コンテナは CRM エンティティを 1 つだけ処理します。エンティティが N 個ある場合は、docker-compose.yml にサービスブロックを N 個追加し、それぞれ別のポートを割り当てます。

services:

  suitecrm-mcp-auth:
    image: ghcr.io/anirudhx7/suitecrm-mcp:v5.4.0
    command: node auth.mjs
    working_dir: /app
    ports:
      - "127.0.0.1:3100:3100"
      - "127.0.0.1:9091:9091"   # auth metrics (Prometheus)
    environment:
      AUTH0_DOMAIN: your-tenant.auth0.com
      AUTH0_CLIENT_ID: your-client-id
      AUTH0_CLIENT_SECRET: your-client-secret
      AUTH0_AUDIENCE: https://your-api-identifier
      GATEWAY_PUBLIC_URL: https://mcp.yourdomain.com
      SESSION_TTL_DAYS: "30"
      PORT: "3100"
      METRICS_PORT: "9091"
      METRICS_BIND: "0.0.0.0"   # 0.0.0.0 required so the Prometheus container can reach it by service name
    restart: unless-stopped

  suitecrm-mcp-crm1:
    image: ghcr.io/anirudhx7/suitecrm-mcp:v5.4.0
    ports:
      - "127.0.0.1:3101:3101"   # expose via reverse proxy only
      - "127.0.0.1:9101:9090"   # entity metrics (Prometheus)
    environment:
      SUITECRM_ENDPOINT: https://crm1.example.com/legacy/service/v4_1/rest.php
      SUITECRM_PREFIX: suitecrm_crm1
      SUITECRM_CODE: crm1
      AUTH0_DOMAIN: your-tenant.auth0.com
      AUTH0_AUDIENCE: https://your-api-identifier
      REQUIRED_GROUP: crm1_users
      PORT: "3101"
      METRICS_PORT: "9090"
      METRICS_BIND: "0.0.0.0"
    depends_on:
      suitecrm-mcp-auth:
        condition: service_healthy
    restart: unless-stopped

  suitecrm-mcp-crm2:
    image: ghcr.io/anirudhx7/suitecrm-mcp:v5.4.0
    ports:
      - "127.0.0.1:3102:3102"   # expose via reverse proxy only
      - "127.0.0.1:9102:9090"   # entity metrics (Prometheus)
    environment:
      SUITECRM_ENDPOINT: https://crm2.example.com/legacy/service/v4_1/rest.php
      SUITECRM_PREFIX: suitecrm_crm2
      SUITECRM_CODE: crm2
      AUTH0_DOMAIN: your-tenant.auth0.com
      AUTH0_AUDIENCE: https://your-api-identifier
      REQUIRED_GROUP: crm2_users
      PORT: "3102"
      METRICS_PORT: "9090"
      METRICS_BIND: "0.0.0.0"
    depends_on:
      suitecrm-mcp-auth:
        condition: service_healthy
    restart: unless-stopped

エンティティごとに変更する項目：

• サービス名（suitecrm-mcp-crm1、suitecrm-mcp-crm2、…）
• SUITECRM_ENDPOINT - 対象 CRM 固有の REST API URL（ドメインの後のパスは SuiteCRM のインストール環境によって異なります）
• SUITECRM_CODE - ツール名と URL ルーティングで使用する短い識別子（例：crm1 の場合、suitecrm_crm1_search、suitecrm_crm1_get などのツール名になります）
• PORT とホスト側のポートマッピング - エンティティごとに固有のポート（3101、3102、…）が必要です

すべてのエンティティで共通の項目：

• AUTH0_DOMAIN と AUTH0_AUDIENCE - すべてのエンティティで 1 つの Auth0 アプリを使用します
• 認証サービス（suitecrm-mcp-auth）は共有され、エンティティのコンテナはこれに依存します

前段にリバースプロキシ（nginx、Caddy）を配置して、/crm1/ をポート 3101 に、/crm2/ をポート 3102 に、/auth/ を任意の 1 つのインスタンスにルーティングします。複数の CRM を本番環境で使用する場合、install.py --config entities.json を使うと、Linux ホスト上でこれらすべてを自動的に設定できます。

↑ トップに戻る

⚙️ 設定

単一エンティティ - 環境変数

複数エンティティ - entities.json

{
  "crm1": {
    "label": "My Company CRM",
    "endpoint": "https://crm.mycompany.com/service/v4_1/rest.php",
    "port": 3101
  },
  "crm2": {
    "label": "Client B CRM",
    "endpoint": "https://crm.clientb.com/service/v4_1/rest.php",
    "port": 3102,
    "tls_skip": true
  }
}

キーはエンティティコード（nginx のパスプレフィックス、ツール名のサフィックス、サービス名）になります。ポートは重複しないようにしてください。

↑ トップに戻る

🔒 TLS

ゲートウェイの HTTPS（Let's Encrypt）

インストーラーに --domain と --email を渡すと、ゲートウェイ自体で HTTPS が有効になります。インストーラーは TLS 終端リバースプロキシとして nginx を設定し、証明書の取得と自動更新のために certbot を実行します。

要件：

• ドメインがこのサーバーのパブリック IP をすでに指していること
• ポート 80（ACME チャレンジ）と 443（HTTPS）が開いていること

インストール中に certbot が失敗しても、ゲートウェイは HTTP で引き続き動作します。DNS またはファイアウォールを修正してから、再実行してください：

certbot --nginx -d your.domain.com -m [email protected] --agree-tos --redirect

自己署名 CRM 証明書

SuiteCRM が自己署名証明書を使用している場合は、エンティティ設定（複数）の "tls_skip": true を追加するか、（単一の場合は）--tls-skip を渡します。これにより NODE_TLS_REJECT_UNAUTHORIZED=0 が設定されます。

信頼できる内部ネットワークでのみ使用してください。TLS 検証をスキップするゲートウェイを、決してパブリックインターネットに公開しないでください。

↑トップに戻る

🔌 クライアントの接続

カスタムリクエストヘッダーを使用した SSE トランスポートに対応する MCP クライアントであれば、どれでも利用できます。 クライアントごとに設定方法が異なります。お使いのクライアント向けの専用ガイドをご覧ください。

Claude Desktop と Claude Code は、SSE 経由でゲートウェイ URL に直接接続します。 ゲートウェイをインストールしたら、SSE エンドポイントと CRM の認証情報を クライアント設定に追加します。単一／複数エンティティの設定、HTTPS の バリエーション、動作確認を含む手順全体は、上記のガイドをご覧ください。

OpenClaw は、2 つのコンポーネントを使用する構成です。ゲートウェイはリモートサーバー 上で実行し（install.py でインストール）、ブリッジプラグインは OpenClaw を 実行するマシン上でローカルに実行します（install-bridge.py でインストール）。ブリッジは SuiteCRM の 24 個すべてのツールをゲートウェイ経由で中継します。OpenClaw のガイドでは、両方のコンポーネントについて最初から最後まで説明しています。

↑トップに戻る

📊 ヘルスチェックと監視

ヘルスチェックエンドポイント

# Shallow health
curl http://YOUR_SERVER:3101/health
# {"status":"ok","entity":"crm1","port":3101,"active":2,"circuit_breaker":"closed"}

# Deep health (pings CRM, returns latency)
curl http://YOUR_SERVER:3101/health/deep
# {"status":"healthy","entity":"crm1","uptime":3600,"connections":2,"circuit_breaker":"closed",
#  "checks":{"endpoint":{"status":"ok","url":"https://crm.example.com"},
#             "api":{"status":"ok","latency_ms":45},
#             "sessions":{"status":"ok","active":2}},"duration_ms":47}

/health/deep は、正常な場合は HTTP 200、CRM に到達できない場合は 503 を返します。レート制限は 1 分あたり 10 リクエストです。

Prometheus メトリクス

2 つのコンポーネントが、別々のポートで Prometheus メトリクスを公開します（localhost のみ）。

# Scrape gateway metrics (single-entity systemd)
curl http://127.0.0.1:9090/metrics

# Scrape auth service metrics
curl http://127.0.0.1:9091/metrics

付属の docker-compose.yml は、両方のサービスを自動的にスクレイプする Prometheus + Grafana + Loki スタックを起動します。環境に GRAFANA_PASSWORD を設定し、http://localhost:3000 にアクセスしてください。

2 つのダッシュボードが自動的にプロビジョニングされます。

• suitecrm-mcp - エンティティごとのビュー：システムの状態、ユーザー／セッション、CRM バックエンド、セキュリティ、ツールの内訳の各行にまたがる 33 個のパネル
• suitecrm-mcp-fleet - 複数エンティティの概要：すべてのエンティティを一覧表示（サーキットブレーカーの状態、接続数、エラー率、レイテンシ）

systemd でインストールした場合は、monitoring/prometheus.yml にスクレイプ対象を追加してください。

scrape_configs:
  - job_name: suitecrm-mcp-auth
    static_configs:
      - targets: ['127.0.0.1:9091']
  - job_name: suitecrm-mcp-crm1
    static_configs:
      - targets: ['127.0.0.1:9101']   # port 3101 + 6000
  - job_name: suitecrm-mcp-crm2
    static_configs:
      - targets: ['127.0.0.1:9102']   # port 3102 + 6000

サーキットブレーカー

ゲートウェイは、エンティティごとに連続した CRM REST API の失敗を追跡します。失敗数が CIRCUIT_BREAKER_THRESHOLD（デフォルトは 5）に達すると、サーキットが開き、CRM にアクセスせずにすべてのツール呼び出しがただちにエラーを返します。CIRCUIT_BREAKER_RESET_MS（デフォルトは 60 秒）経過後、サーキットは半開状態になり、プローブ呼び出しを 1 回許可します。プローブが成功するとサーキットは閉じ、失敗すると開いたままになります。

これにより、応答の遅い CRM や応答しない CRM が接続を占有し、MCP クライアントでタイムアウトが連鎖的に発生するのを防ぎます。

現在の状態は、/health と {prefix}_server_info ツールのレスポンスの両方に表示されます。

↑ 先頭に戻る

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

サービスのステータスを確認：

sudo python3 install.py --status

ログを表示：

journalctl -u suitecrm-mcp -f          # single
journalctl -u suitecrm-mcp-crm1 -f     # multi

ゲートウェイのヘルスをテスト：

curl https://mcp.yourserver.com/health

よくある問題：

• HTTP 401 on SSE - API キーが無効または期限切れです。/auth/login で再認証してください
• HTTP 403 on SSE - ユーザーがこのエンティティに必要なグループに属していません。ID プロバイダーのグループメンバーシップを確認してください
• OAuth コールバックエラー - OAUTH_REDIRECT_URI が ID プロバイダーに登録された値と完全に一致していることを確認してください
• OAuth 後に CRM login failed - CRM ユーザーが見つからないか、API アクセスが有効になっていません。mcp-admin list を実行して、ユーザーのプロファイルが Redis にあることを確認してください
• Non-JSON response - CRM エンドポイント URL が間違っています。末尾が /service/v4_1/rest.php であることを確認してください
• ECONNREFUSED - サービスが起動していません。journalctl -u suitecrm-mcp を実行してください
• SSE 接続が切断される - 長時間アイドル状態が続く場合は正常です。クライアントは自動的に再接続します

↑ 先頭に戻る

✅ 対応する SuiteCRM のバージョン

SuiteCRM 8.8.x でテスト済みです。v4_1 REST API を公開している SuiteCRM のすべてのバージョンで動作するはずです。この API は初期の SuiteCRM リリースから提供されています。

SugarCRM には対応していません。SuiteCRM からフォークされた後、API に大きな違いが生じています。

エンドポイント URL の確認方法

REST API のパスは、SuiteCRM のインストール方法によって異なります。一般的なパターンは次のとおりです。

https://crm.example.com/service/v4_1/rest.php
https://crm.example.com/legacy/service/v4_1/rest.php
https://crm.example.com/crm/service/v4_1/rest.php
https://crm.example.com/crm/public/legacy/service/v4_1/rest.php

エンドポイントを確認するには、SuiteCRM にログインし、管理 → 診断ツールに移動してサイト URL を確認するか、サーバーの管理者に問い合わせてください。エンドポイントの末尾は必ず /service/v4_1/rest.php です。異なるのはその前のプレフィックスだけです。次のコマンドでテストできます。

curl -s -X POST "https://YOUR-PATH/service/v4_1/rest.php" \
  --data 'method=get_server_info&input_type=JSON&response_type=JSON&rest_data={}'
# Should return: {"flavor":"CE","version":"...","gmt_time":"..."}

↑ トップに戻る

⚠️ 既知の制限事項

LDAP / SSO ユーザーは REST API 経由で認証できません

SuiteCRM の v4_1 REST API は、ローカルデータベースのパスワードに対してのみ認証します。組織で LDAP、Active Directory、または SSO を使用している場合、それらのプロバイダー経由で CRM のウェブ UI にログインするユーザーにはローカルパスワードが設定されていません。そのため、認証情報が正しくてもゲートウェイは Invalid Login を返します。

回避策： CRM VM 上で crm-provision-user（--setup-crm-host によってデプロイされます）を使用し、既存の LDAP / SSO ユーザーのウェブログインには触れずにローカル API パスワードを設定します。単一ユーザーと CSV による一括モードに対応しています。

# SSH into the CRM VM, then:

# Single user
sudo crm-provision-user john.doe secretpassword

# Bulk - CSV format: username,password
sudo crm-provision-user --csv /path/to/users.csv

これは SuiteCRM REST API の制限であり、このゲートウェイ固有のものではありません。

↑ トップに戻る

🛡️ セキュリティに関する注意事項

• 本番環境では HTTPS が必須です。 OAuth フローと API キーを平文の HTTP 経由で送信してはいけません。--domain を使用して Let's Encrypt を有効にするか、TLS 終端プロキシの背後にゲートウェイを配置してください。
• API キーは個人ごとに発行され、取り消し可能です。 各ユーザーには、そのユーザーの ID に紐づいた専用のキーが発行されます。管理者は mcp-admin revoke <sub> を使って、キーを即座に取り消せます。キーが漏洩しても、他のユーザーの情報は公開されません。
• CRM パスワードがゲートウェイの外に出ることはありません。 クライアントマシン（Claude Desktop、Claude Code、OpenClaw）が保持するのは、不透明な API キーのみです。CRM の認証情報は、ゲートウェイ上の Redis の crm:profiles ハッシュに保存されます（Redis 認証とネットワークバインドによってアクセスを制御します）。
• AUTH0_CLIENT_SECRET は秘密にしてください。 /etc/suitecrm-mcp/auth.env（モード 600）に保存され、認証サービスのみが読み取ります。
• 環境ファイルはモード 600、環境ディレクトリはモード 700 で書き込まれます。
• entities.json は .gitignore に含まれています。絶対にコミットしないでください（CRM エンドポイントとグループ名が含まれています）。

制御の詳細と既知の制限事項については、SECURITY.md を参照してください。

↑ トップに戻る

📄 ライセンス

MIT