FavCRM

FavCRM MCP

FavCRM Model Context Protocol サーバーのインストール用スニペット、例、ドキュメントです。サーバー本体は https://api.favcrm.io/mcp でホストされています。このリポジトリはクライアントの設定とコミュニティのサンプルを提供します。

MCP 経由で公開される、顧客、予約、イベント、ロイヤルティ、請求書、支払い、WhatsApp／SMS／メールに関する、型付けされた 231 個のツールです。Streamable HTTP トランスポートに対応するエージェント型クライアントであれば、どれでも使用できます。

エンドポイントでは、?profile=<name> または X-FavCRM-MCP-Profile で選択する、用途に特化したツールプロファイルをサポートしています。

• compact は、大規模エージェントのランタイム向けに、search_tools と execute_tool による小規模な検出／ルーティング用インターフェースを公開します。
• platform は、スーパー管理者向けの顧客ワークスペースおよび会社設定の操作のみを公開します。有効な加盟店会社がなくても動作し、生の SQL は決して公開しません。
• full はクライアントやスキャナー向けのデフォルトのままです。

プラットフォーム運用者は、専用の Cursor または Claude Desktop 設定から開始できます。通常の加盟店 API キーでは、プラットフォームツールにアクセスできません。

🤖 AI エージェントスキル

AI エージェントを使って FavCRM のヘッドレスバックエンドを構築していますか？公式スキルをインストールして、ベストプラクティス、標準業務手順、MCP ツールの構成を AI に学習させましょう。

# Example: Install the Booking Operator skill
npx skills add https://github.com/favcrm/mcp/tree/main/skills/favcrm-booking-operator

# Or install all skills at once
npx skills add favcrm/mcp

利用可能なエージェントスキルの一覧については、skills/ ディレクトリをご覧ください。

公開エージェントスキルは skills/ にあります。エージェントによる登録、チームのオンボーディング、チャネルの設定、予約業務、顧客ライフサイクル、コミュニケーションの承認、請求／コマース、コンテンツ、営業業務、ナレッジトレーニング、レポート作成のための、移植可能なワークフローパッケージです。エージェントやマーケティング担当者がソースを閲覧できます。一方、FavCRM のランタイムでは、プラットフォームのスキルレジストリを通じて、審査済みのバージョンをインストールします。

クライアント	状態	設定
Vercel v0	✅ 利用可能	マーケットプレイスからインストール — ワークスペースを自動プロビジョニングし、環境変数を注入します
Cursor	✅ 利用可能	mcp.json スニペット
Smithery	✅ 利用可能	smithery mcp add favcrm/favcrm
Claude Desktop / Connector	🚧 保留中	OAuth プロバイダー（フェーズ 3、約 3 週間）
ChatGPT Apps Directory	🚧 保留中	掲載審査中
Windsurf / Continue.dev / Zed	✅ 動作します	Cursor と同じ mcp.json 形式

---

キーを取得する

方法は 2 つあります。

オプション A — エージェントに登録してもらう（フォーム入力やポータルのクリックは不要）

まず、プレースホルダーの環境変数を使って FavCRM をクライアントに接続します（下の Cursor セクションを参照）。次に、エージェントに次のように依頼します。

「FavCRM に登録してください。香港にある Stretch + Breathe というヨガスタジオです。」

エージェントは次の操作を行います。

1. register_organisation_request を呼び出します。サーバーから 6 桁のコードがメールで届きます
2. チャットにコードを貼り付けます
3. エージェントが register_organisation_verify を呼び出し、サーバーから新しい fav_mcp_* キーが返されます
4. エージェントがキーを保存し、すぐに作業を開始します

移植可能な SKILL.md ワークフローについては、skills/favcrm-agentic-registration をご覧ください。

内部では、OTP の有効期間は 10 分で、メール所有権を実際に確認し、IP ごとにレート制限（1 時間あたり 3 回、1 日あたり 20 回）を設けています。フィッシングの余地や、偽のデモはありません。

オプション B — 従来の方法で登録する

favcrm.io/signup → ポータル → Settings → MCP Keys → fav_mcp_* の値をコピーします。

既存の FavCRM 加盟店も同じ場所から取得できます。MCP アクセスにプランのアップグレードは不要です。

無料プラン（どちらの方法でも）： 顧客 100 件、月 200 件の予約、月 1,000 回の MCP 呼び出し、上限引き上げの 30 日間トライアル。

CLI からの初期設定

favcrm CLI でも、初期状態からのセットアップを実行できます。

favcrm signup request --email [email protected] --organisation-name "Ada Studio"
favcrm signup verify --request-id <request-id> --code <code>
favcrm doctor
favcrm team invite create --email [email protected] --role staff
favcrm whatsapp status
favcrm whatsapp connect --mode cloud-api

チームへの招待を受けたユーザーは、既存の API キーがなくても招待を受け入れられます。

favcrm team invite accept-request --token <invite-token>
favcrm team invite accept-verify --token <invite-token> --code <code>

---

Cursor

検証済みの形式です。cursor.com/docs/mcp。

~/.cursor/mcp.json（またはプロジェクト内の .cursor/mcp.json）：

{
  "mcpServers": {
    "favcrm": {
      "url": "https://api.favcrm.io/mcp",
      "headers": {
        "Authorization": "Bearer ${env:FAVCRM_API_KEY}"
      }
    }
  }
}

次に、Cursor のプロセスが環境変数を読み取る場所でキーをエクスポートします。

# shell rc
echo 'export FAVCRM_API_KEY=fav_mcp_...' >> ~/.zshrc

# or per-project (direnv)
echo 'export FAVCRM_API_KEY=fav_mcp_...' >> .envrc

Cursor を再起動 → Settings → MCP → favcrm に接続 → 231 個のツールがチャットに追加されます。

${env:VAR} をインラインで指定する代わりに使う理由は何ですか？Cursor はリクエスト時に環境変数を展開するため、キーがリポジトリや共有設定に保存されることはありません。

---

Smithery

Smithery の favcrm.io — CLI からインストールします。

npm i -g @smithery/cli
smithery login
smithery mcp add favcrm/favcrm

プロジェクトスコープでインストールする場合、smithery mcp add favcrm/favcrm --client cursor を実行すると、適切な mcp.json のブロックが書き込まれます。

---

Claude Desktop

🚧 OAuth ベースのコネクターはフェーズ 3 で対応予定です。利用可能になったら：

1. claude.com → Connectors → Add custom connector
2. URL：https://api.favcrm.io/mcp
3. OAuth で認証 → ワークスペース選択 → ツール一覧

それまでは、上級ユーザーは Cursor と同じ Bearer ヘッダーの方式で FavCRM を Claude Desktop の claude_desktop_config.json に設定できます（コミュニティのみの方法で、現在 Anthropic のコネクターディレクトリには掲載されていません）。

---

ChatGPT

🚧 Apps Directory への掲載は審査中です。承認されたら：

1. ChatGPT → Tools メニュー → Apps → 「FavCRM」を検索
2. 追加 → OAuth ハンドシェイク → ワークスペース選択
3. 厳選された 26 個のツールがチャットに追加されます（読み取り中心＋安全な書き込み。破壊的な操作には確認が必要です）

---

テストする

設定が有効になると、ChatGPT／Cursor／Claude にツールが自動的に表示されます。コマンドラインから簡単にテストするには：

# Discovery (no auth needed — public-scan endpoint)
curl https://api.favcrm.io/.well-known/mcp/server-card.json | jq '.tools | length'
# → 231

# Auth + initialize
curl -s https://api.favcrm.io/mcp \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer $FAVCRM_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}' \
  | jq

# Call a read-only tool
curl -s https://api.favcrm.io/mcp \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer $FAVCRM_API_KEY" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"list_membership_tiers","arguments":{}}}' \
  | jq

詳細は examples/ をご覧ください。

---

ツールの概要

28 個のスコープに 231 個のツールがあります。すべてのツールに次のアノテーションが付与されています。

• title — 人が読めるラベル
• readOnlyHint — list_* / get_* / search_* などの場合は true
• destructiveHint — delete_* / cancel_* / void_* / refund_* の場合は true
• openWorldHint — 外部サービス（WhatsApp、Stripe、メール）にアクセスするツールの場合は true
• idempotentHint — set_* / update_* / upsert_* および読み取り専用の場合は true

クライアントはこれらを使って破壊的な呼び出しを制限したり、コストを見積もったりできます。完全なカタログは https://api.favcrm.io/.well-known/mcp/server-card.json が正本です。ここに掲載されている内容は要約のみです。

コンパクトなツールセットやコンテキスト依存のツールセットを使うエージェントは、search_tools で操作を検索してから、選択したツールを execute_tool で実行してください。動作や引数の形式を推測する前に、プラットフォームのドキュメントを query_favcrm_platform で確認してください。加盟店固有の情報、ポリシー、価格に関する注記、FAQ、ブランドガイドラインについては、query_company_knowledge を使ってください。完全なドキュメントではなく、ソースドキュメント ID 付きのスニペットが返されます。

スコープ	ツールの例	読み取り専用	書き込み
contacts	search_members、get_member_profile、create_account、attach_tags	5	6
customer_segments	list_segments、preview_segment_count、set_segment_members	4	4
custom_fields	list_custom_fields、create_custom_field、set_custom_field_values	3	4
bookings	list_services、get_available_slots、create_booking	12	15
events	list_event_registrations、get_event_campaign_exclusions	2	0
membership	list_tiers、enrol_membership、earn_loyalty_points	4	3
shop	list_products、get_order、create_order	8	6
invoices	list_invoices、mark_invoice_paid	4	4
campaigns	list_campaigns、send_campaign（制限付き）	5	3
blog	list_posts、publish_post	14	13

スーパー管理者向けのプラットフォームツールでは、別のスコープ群を使用します。

スコープ	機能
platform:customer_setup	顧客のワークスペースを検索・作成し、会社の設定を行います
platform:catalog	完全なプロファイルで、グローバルなプラン、モジュール、AI メディアのカタログを管理します
platform:sql_read	完全なプロファイルで、緊急時に SELECT / EXPLAIN にアクセスできます
platform:sql_write	完全なプロファイルで、緊急時に DML にアクセスできます
platform:*	すべてのプラットフォーム機能。管理された内部オペレーターに限って使用してください

SQL スコープは明示的に指定する必要があります。また、platform プロファイルでは platform:* を指定しても SQL ツールは利用できません。

---

エージェントの問題報告

MCP ネイティブの手段が見つからない、ツールのスキーマが分かりにくい、ツールが予期せず失敗した、または REST / SDK の動作にフォールバックする必要があった場合は、エージェントから report_agent_issue を呼び出してください。期待する動作、実際の動作、試した手順、関連するツール呼び出しやログ、AI による分析、確認事項を含めてください。FavCRM はこれらの報告をプラットフォームサポートのトリアージキューに転送します。

例：

favcrm tool call report_agent_issue '{"title":"Missing account creation MCP tool","severity":"high","area":"mcp_tool_missing","expectedBehavior":"Agent can create an account via MCP only.","actualBehavior":"Agent had to use SDK fallback.","stepsTried":["Listed tools","Tried create_contact"],"aiAnalysis":"Account creation exists in backend services but was not exposed in MCP."}'

プランの操作

エージェントは MCP を離れることなく、プランへのアクセスを確認し、事前チェックできます。

favcrm tool call get_plan_status '{}'
favcrm tool call check_plan_operation '{"toolName":"create_account"}'
favcrm tool call list_plan_options '{}'
favcrm tool call create_plan_upgrade_link '{"planCode":"favcrm-lite","billingCycle":"monthly","confirm":true}'

モジュール、スコープ、サブスクリプション、またはクォータの制限にかかる可能性のある書き込みの前に、check_plan_operation を使用してください。結果に upgradeAction が含まれている場合は、返されたアクションをユーザーに表示してください。Stripe のリンクは confirm=true を指定した create_plan_upgrade_link でのみ作成されます。

---

認証モード

トークンの種類	有効期間	用途
fav_mcp_* API key	長期間有効、失効可能	Cursor、Windsurf、Zed、Continue.dev、スクリプト
fav_v0_* partner token	Vercel プロジェクトごと、スコープ限定	v0 / Vercel のインストールのみ
OAuth bearer (15-min JWT + 30-day refresh)	短期間有効	Claude Connectors（フェーズ 3）、ChatGPT Apps
OTP-issued JWT (60 min)	短期間有効	対話型の人間（マーチャントポータルでの交換）

マーケットプレイストークン（fav_v0_*、OAuth 発行）は、基盤となるスコープにかかわらず、スーパー管理者ツール（生 SQL、プラン管理）から完全にブロックされます。これはトークン単位の RBAC だけでなく、リクエスト層で防御を多層化するものです。

---

料金

プラン	価格	制限
Free	$0	顧客 100 件 · 予約 月 200 件 · MCP 呼び出し 月 1,000 回
Lite	$19 / 月	1 席 · メールでのコミュニケーション · エージェント経由の BYO-AI
Starter	$49 / 月	3 席 · AI クレジット 100 万 · WhatsApp + SMS · 会議メモ
Enterprise	カスタム	席数無制限 · 複数拠点 · カスタムルーティング

全プランの一覧はこちら：favcrm.io/pricing。

---

問題報告 / 貢献

• ツールの動作や MCP トランスポートのバグ：こちらから Issue を作成してください。
• 新しいクライアント（Cline、Replit Agent、Roo など）の例：examples/ への PR を歓迎します。
• エージェントのワークフロースキル：skills/ への PR を歓迎します。
• 貢献ガイドライン：CONTRIBUTING.md。
• セキュリティに関する報告：SECURITY.md に従ってください。脆弱性に関する Issue を公開しないでください。
• サーバーのバグ / 新しいツールのリクエスト / 商用に関するお問い合わせ：[email protected]。

---

リンク

• favcrm.io — ランディングページ
• favcrm.io/integrations/vercel · /cursor · /chatgpt — プラットフォーム別のインストールガイド
• favcrm.io/developers — 開発者向けドキュメント一式
• favcrm.io/pricing — 料金一覧
• favcrm.io/privacy-policy · /terms-of-use

ブランドアセット

背景プレート付きのマーケットプレイス向け 1:1 アイコンは、assets/ にあります：

ファイル	用途
assets/icon.png	512×512 PNG — Cursor / Smithery / mcp.so の掲載用
assets/favcrm-icon-256-dark.svg	1:1 SVG、インク色のプレート、明色のグリフ — ほとんどのマーケットプレイス向け
assets/favcrm-icon-256-light.svg	1:1 SVG、キャンバス色のプレート、インク色のグリフ — ライトテーマの UI 向け
assets/favcrm-icon-256-dark.png	256×256 PNG のフォールバック

すべてのアイコンはアスペクト比 1:1 で、角丸の正方形プレート（256 単位のグリッド上で角の半径は 48px）と、中央に配置された「fav.」のワードマークグリフを備えています。

ライセンス

このリポジトリ（ドキュメント + 例）は MIT ライセンスです。詳細は LICENSE をご覧ください。ホスト型 MCP サーバーは FavCRM のプロプライエタリな SaaS であり、インストールには FavCRM アカウントが必要です。