MCP-Excel

MCP-Excel — Google Sheets CRM MCP サーバー

任意の Google Sheet を 4 エンティティの CRM（Lead、Organization、Contact、Activity）に変換する、ステートレスな MCP サーバーです。スタンドアロンの HTTP サービス（FastMCP streamable-HTTP、デフォルトポート 5002）として、または Claude Desktop などのローカル MCP ホスト向けに stdio 経由で動作します。ゲートウェイ、ngrok、サブプロセスの起動は不要です。

---

アーキテクチャ

Any MCP host (Claude Desktop, your backend, an agent framework)
  │  HTTP POST /mcp  (JSON-RPC) — or stdio
  ▼
MCP-Excel :5002  (FastMCP streamable-HTTP)
  │  gspread
  ▼
Google Sheets API

すべてのツール呼び出しには明示的な sheet_id が含まれます。セッション状態や「アクティブなシート」変数はありません。リクエスト間で共有されるものがないため、複数のチームが同じ稼働中のインスタンスを安全に使用できます。

---

シートスキーマ（自動管理）

4 つのタブは、接続時に存在しない場合に作成されます。既存のタブはそのまま使用され、不足している列は既存データに影響を与えずに追加されます。

タブ	主キー	主な列
Lead	Lead ID	Organization ID, Status, Segment, Opportunity Details, Last Contact Date
Organization	Organization ID	Organization Name, Industry Domain, Sub Domain, Company Type, Website
Contact	Contact ID	First Name, Last Name, Organization ID, Designation, Mobile, Email, LinkedIn Profile
Activity	Activity ID	Lead ID, Organization ID, Contact ID, Activity Type, Activity Sub-Type, Subject, Discussion Summary, Outcome

ID は既存のパターンを引き継いで自動採番されます（LD001 → LD002、ACT010 → ACT011）。一貫したパターンが見つからない場合は UUID にフォールバックします。

各タブには、まだ存在しない場合、監査用の Created At、Updated At、Deleted 列も追加されます。

ヘッダーはあいまい一致で照合されるため（同義語や類似した列名を解決します）、列名が多少異なる既存のシートでも動作します。実際に重複している列を統合するには、まずドライランで tool_dedupe_headers を実行してください。

---

セットアップ

1. Google サービスアカウント

Google Sheets API と Google Drive API を有効にした creds.json サービスアカウントキーが必要です。

このディレクトリ（デフォルトのパス）に配置するか、GOOGLE_APPLICATION_CREDENTIALS にフルパスを設定してください。

creds.json を git にコミットしないでください。 .gitignore で除外されています。ローカルに保管するか、シークレットとしてマウントしてください。

2. シートを共有する

接続する Google Sheet ごとに、シートを開き → Share → サービスアカウントのメールアドレスを Editor として追加 → Done をクリックします。

サービスアカウントのメールアドレスは起動時に表示され、権限エラー時には get_sheet_info によって返されます。また、creds.json からも確認できます。

python3 -c "import json; print(json.load(open('creds.json'))['client_email'])"

3. 依存関係をインストールする

pip install -r requirements.txt

オプション — 名刺の OCR（Claude Vision）サポート：

pip install anthropic
export ANTHROPIC_API_KEY=...

---

実行方法

ローカル開発（HTTP、:5002）

GOOGLE_APPLICATION_CREDENTIALS=creds.json python mcp_excel_server.py

正常に動作していることを確認します：

curl -s -X POST http://localhost:5002/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' \
  | python3 -m json.tool

Docker（ステージング／本番環境）

docker build -t mcp-excel .
docker run -p 5002:5002 \
  -v /path/to/creds.json:/secrets/creds.json \
  -e GOOGLE_APPLICATION_CREDENTIALS=/secrets/creds.json \
  mcp-excel

Claude Desktop（stdio トランスポート）

HTTP の代わりに stdio を使用するには、MCP_TRANSPORT=stdio を設定します。

{
  "mcpServers": {
    "crm": {
      "command": "python",
      "args": ["/path/to/mcp-excel/mcp_excel_server.py"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/mcp-excel/creds.json",
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}

---

環境変数

変数	デフォルト	説明
GOOGLE_APPLICATION_CREDENTIALS	creds.json	サービスアカウント JSON のパス
MCP_TRANSPORT	http	サーバーモードでは http、Claude Desktop では stdio
MCP_PORT	5002	HTTP のリッスンポート
ANTHROPIC_API_KEY	—	tool_extract_business_card 専用

---

ツール

すべてのツールはステートレスです。呼び出しごとに sheet_id（Google Sheets の完全な URL またはスプレッドシート ID のみ）が必要です。

ツール	説明
tool_get_sheet_info	アクセスを検証し、4 つすべてのタブが存在することを確認して、書き込み権限を確認します
tool_add_record	Lead／Organization／Contact／Activity にレコードを追加します
tool_list_records	任意の列ベースのフィルターを適用してレコードを一覧表示します（ページ分割）
tool_search_records	すべての列を対象にキーワード検索します
tool_update_record	主キー ID を指定して既存のレコードのフィールドを更新します
tool_delete_record	レコードを論理削除します（Deleted を true に設定します）
tool_get_related_records	外部キーを使ってレコードを検索します（例：Lead に関連するすべての Activity）
tool_get_pipeline_analytics	Lead パイプラインの分析：合計、ステータス別内訳、セグメント別内訳
tool_dedupe_headers	重複する列を検索して統合します（最初にドライランのレポートを表示します）
tool_extract_business_card	Claude Vision を使って名刺画像から連絡先フィールドを抽出します（ANTHROPIC_API_KEY が必要です）

---

開発

pip install pytest
pytest test_mcp_excel.py test_crm_local.py -v

テストは完全にオフラインで実行されます（Google 呼び出しはモック化されています）。認証情報は不要です。

---

トラブルシューティング

問題	対処方法
status: failure, message: ""	シートが見つかりません。サービスアカウントを編集者として共有してください
Permission denied on sheet	サービスアカウントと再共有してください。権限は閲覧者ではなく編集者にしてください
Cannot connect to MCP-Excel service	MCP-Excel が起動していません。:5002 で起動してください
sheet_id is required and was empty	必ず sheet_id を渡してください。暗黙的に選択されるアクティブシートはありません
タブが見つからない／列が正しくない	get_sheet_info が不足しているタブを自動作成し、不足している列を追加します

---

ライセンス

MIT — LICENSE を参照してください。Nife が作成しました。