Livespace CRM MCP Server

Livespace CRM MCP サーバー

Livespace CRM 向けの非公式 MCP サーバーです。生の API をそのまま反映するのではなく、意図に沿った 11 個のツールを提供し、MCP 仕様 2026-07-28 のステートレスな Streamable HTTP トランスポートを対象としています。

バージョン 0.1.2 は npm、公式 MCP Registry、および GitHub Release で公開されています。

v1 の実装はこのリポジトリで完了しています。読み取り専用ツール 6 個と任意の書き込みツール 5 個を備え、デフォルトは読み取り専用で、API アクセスの範囲が制限され、エラーはサニタイズされ、確認にはエリシテーションを優先するフローを採用しています。評価時にはテスト用の Livespace アカウントを使用してください。

この構成を採用した理由

Livespace の RPC API には約 80 個のメソッドがありますが、並べ替え、集計、案件ステージを直接設定する操作はありません。このサーバーは、低レベルの呼び出しを MCP クライアントが安全に利用できるタスクにまとめています。

• ID を使用する前の探索；
• 範囲を制限した検索、レコードの読み取り、分析；
• 書き込み前の一括プレビュー；
• 項目ごとの結果と書き込み後の確認；
• Livespace 固有のステージ移動と通知の明示的な処理。

ツール

ツール	モード	用途と上限
health	読み取り	サーバーを確認します。checkLivespace: true を指定すると、軽量な Livespace API 呼び出しも 1 回実行します。
crm_metadata	読み取り	プロセス、ユーザー、グループ、ソース、タスク辞書、製品、現在のユーザーなど、9 つの辞書セクションを返します。任意の userQuery を指定すると、500 行の上限を適用する前に、名前またはメールアドレスでユーザーを絞り込みます。
search_crm	読み取り	個人、会社、案件を検索します。簡易結果にもレコードへのリンクが含まれます。案件を並べ替えて検索する場合は、200 件のレコードを対象に並べ替え、結果が切り詰められたかどうかを報告します。
get_records	読み取り	1 種類のレコードから最大 25 個の ID を読み取ります。個人、会社、案件は最大 5 件までです。
get_activity	読み取り	1 件のレコードウォール、範囲を限定した CRM フィード、または範囲を限定したタスクページを、呼び出しごとに読み取ります。
analyze	読み取り	範囲を限定したウィンドウに対し、名前付きの集計を 1 つ実行し、ソースウィンドウのデータが切り詰められたかどうかを報告します。
create_records	書き込み	個人、会社、案件、タスクを作成します。呼び出しごとに最大 10 件です。デフォルトでは完全一致する連絡先の重複を検出します。
update_records	書き込み	個人、会社、案件、タスクを更新します。呼び出しごとに最大 10 件です。
log_activities	書き込み	公開メモまたは電話記録を追加します。呼び出しごとに最大 15 件のメモまたは電話記録を追加できます。
move_deals_to_stage	書き込み	プロセスステップに最小限の差分を適用して案件を移動します。呼び出しごとに最大 10 件です。後方への移動には明示的な許可リストが必要です。
notify_user	書き込み	アプリ内通知を 1 件送信します。10 分あたり最大 5 件、受信者 1 人あたり 1 分に 1 件までです。

Livespace には「ステージを設定する」呼び出しがないため、move_deals_to_stage はプロセスステップのチェックとチェック解除によって機能します。案件のステージは、チェック済みの最も先のステップで決まります。そのため、後方へ移動するには完了済みのステップのチェックを外す必要があり、これによりチェックボックスの履歴上の意味が変わる可能性があります。

notify_user は受信者を検証し、レコードへのディープリンクを追加できます。Livespace には通知を読み返す機能がないため、このツールが報告するのはリクエストが正常にディスパッチされたことだけであり、配信されたことではありません。

要件

• API アクセスが可能な Livespace プラン。現在は Automation 以上です。
• Account settings -> API -> Users から取得した Livespace API キーとシークレット。MCP が必要とする権限だけを付与した専用の Livespace API ユーザーを使用してください。すべての API 操作はそのユーザーの権限を引き継ぎます。
• Bun 1.3.14 以降（bun.sh）。現在のサーバーは Bun.serve を使用しており、Node.js または Cloudflare Workers のアダプターはありません。

v1 のデプロイモデルは単一ユーザー向けです。Livespace の認証情報 1 組と、有効にした場合はサーバーを保護する MCP ベアラートークン 1 つを使用します。OAuth や、複数ユーザー向けの認証情報ルーティングには対応していません。

npm からインストールして実行する

このパッケージは npm の公開レジストリを通じて配布されていますが、ランタイムには Bun を使用します。実行に Node.js や npm CLI は必要ありません。

初めて試す場合は、Git リポジトリの外に専用の作業ディレクトリを作成します。そこに、独自の Livespace 認証情報を記述した .env ファイルを追加します。

LIVESPACE_SUBDOMAIN=
LIVESPACE_API_KEY=
LIVESPACE_API_SECRET=

3 つの空の値を入力し、ファイルを保護してから、公開済みパッケージを起動します。

chmod 600 .env
bunx livespace-crm-mcp

デフォルトのエンドポイントは http://127.0.0.1:3020/mcp です。MCP クライアントが接続している間は、プロセスを実行したままにしてください。まず読み取り専用モードで起動して health を呼び出し、その後、ユーザー、プロセス、ステージ、グループ、または辞書の ID が必要な操作を実行する前に crm_metadata を使用してください。

bunx は npm からパッケージをダウンロードし、ローカルにキャッシュします。このリリースを固定するには、bunx [email protected] を実行します。

MCP クライアントを接続する

Streamable HTTP に対応したクライアントを、次のサーバー URL で設定します。

{
  "url": "http://127.0.0.1:3020/mcp"
}

正確な設定フィールドはクライアントによって異なります。MCP_AUTH_TOKEN を設定し、ループバック接続の場合も含め、クライアントが Authorization: Bearer <your-token> を送信するよう設定してください。書き込みツールを有効にする場合、認証は必須です。

このパッケージが提供するのは Streamable HTTP であり、stdio ではありません。一部の MCP クライアントはローカル URL に接続できますが、bunx を起動できないため、コマンドは別のターミナルで起動してください。stdio のみに対応したクライアントは、現時点ではサポートされていません。各 HTTP リクエストには JSON-RPC メッセージを 1 つ含める必要があります。トップレベルのバッチ配列は、ディスパッチ前に拒否されます。

読み取り結果

レコードデータは structuredContent に格納され、短いテキストの概要が添えられます。ホストが両方のチャネルをモデルに渡していることを確認してください。search_crm と get_activity で結果ページが空の場合、両方のチャネルに同じ hint が含まれます。一致するレコードがないと判断する前に、返されたカーソルを使って続きを取得してください。crm_metadata のユーザー検索で結果が空の場合も、両方のチャネルにヒントが含まれます。テスト済みバージョン、確認の制限、CRM にアクセスせずに実行できる合成フィクスチャについては、ホスト互換性チェックを参照してください。

crm_metadata の userQuery を使うと、名前またはメールアドレスの一部からユーザーを検索できます。たとえば、{"userQuery":"[email protected]"} を指定すると、ユーザーセクションのみが返されます。クエリは前後の空白を除いて 2～100 文字である必要があります。検索では大文字と小文字は区別されませんが、アクセント記号は区別されます。チーム名は検索されません。sections を指定する場合は、users を含める必要があります。ほかに要求したセクションはフィルターされません。クエリを省略すると、通常どおりセクションが選択されます。

ツールは、辞書順で一致したユーザーを最大 500 件返します。担当者または書き込み先を選ぶ前に、複数の一致がある場合は絞り込んでください。totalItems は、この上限を適用する前のキャッシュ済み辞書における一致件数です。特にユーザーが結果に見つからない場合は、asOf、ageMs、stale を確認してください。

フレーズ検索のリンクは、個々のリンク先を別途確認せずに、API ID からローカルで生成されます。使用できない ID の場合、url は空になります。レコードの読み取りとフィルター検索では、Livespace が提供する URL が保持されます。これは、人物、会社、案件の detail: "minimal" の場合も同様です。この URL も空の場合があります。タスクにはレコード URL がありません。

detail によって除外されたフィールドは返されません。返された値が空または null でも、応答に値がないことを示すだけであり、CRM フィールドが空であることやアクセス制限があることを意味するわけではありません。案件の金額と確度では、数値のゼロと null を区別してください。予算がゼロであることだけでは、意図的に設定されたかどうかは分かりません。一部のカウンターとフラグでは、欠損データがゼロまたは false に正規化されるため、これらのデフォルト値だけでは、明示的に値が保存されているとは限りません。

案件の value は、アカウントで入力されているフィールドの値です。予算内訳を使用するアカウントでは、内訳の合計が value に格納されます。それ以外のアカウントでは、すべての案件で value: 0 が報告され、UI に表示される金額は value_final に格納されます。サーバーは、value_final がゼロ以外の場合はその値を、そうでない場合は value を返します。そのため、どちらの種類のアカウントでも search_crm、get_records、analyze の結果は UI と一致します。

detail: "full" の場合、案件には checkedSteps（完了としてマークされたプロセスのステップ。ステージとステップの ID および名前を含みます）と、受注、失注、期限切れの理由名およびメモも含まれます。案件が再開されても以前の失注理由が残る場合があるため、先に status を確認してください。search_crm のフィルターでは、人物、会社、案件に createdFrom と createdTo、案件に modifiedFrom を指定できます。いずれも両端を含む YYYY-MM-DD 形式の日付です。Livespace は読み取れない日付を無視してすべてのレコードを返すため、サーバーは Livespace の呼び出し前に無効な日付を拒否します。案件の status フィルターには open（デフォルト）、won、lost、outdated、all を指定できます。

すべてのツールは、未対応の入力パラメーターを拒否します。クライアントから入力検証エラーが報告された場合は、引数を修正してください。

設定

変数	用途
LIVESPACE_SUBDOMAIN	プロトコルと .livespace.io を含まないアカウントのサブドメインです。
LIVESPACE_API_KEY / LIVESPACE_API_SECRET	1 人の Livespace ユーザーの認証情報です。
MCP_PORT	サーバーのポートです。デフォルト：3020。
MCP_BIND_HOST	バインドアドレスです。デフォルト：127.0.0.1。
MCP_AUTH_TOKEN	32 バイト以上のランダムなベアラートークンです。書き込み時、およびループバック以外のアドレスにバインドする場合に必須です。すべてのサーバーでの設定を推奨します。
LIVESPACE_MCP_ENABLE_WRITES	書き込みツールを公開するには true に設定します。デフォルト：false。
LIVESPACE_MCP_READ_ONLY	緊急停止スイッチです。true にすると、上記で有効にしていても書き込みツールが削除され、ブロックされます。
MCP_REQUEST_STATE_KEY	書き込み確認の署名に使用する、独立した 32 バイト以上のランダムな秘密鍵です。書き込みを有効にする場合に必須です。
MCP_ALLOW_UNBOUND_WRITE_CONFIRMATION	フォームによる情報取得に対応していないクライアント向けの、安全でない互換モードです。デフォルト：false。
MCP_ALLOWED_HOSTS	DNS リバインディング対策のための Host ヘッダー許可リストです。ループバック以外のアドレスにバインドする場合に必須です。
MCP_ALLOWED_ORIGIN_HOSTNAMES	ブラウザーの Origin に対する追加のホスト名を任意で指定します。ループバック以外のアドレスにバインドする場合、デフォルトで MCP_ALLOWED_HOSTS が使用されます。
MCP_RATE_LIMIT_PER_MINUTE / MCP_RATE_LIMIT_BURST	プリンシパルごとのリクエストレートです。デフォルトは、毎分 120 件、バースト 30 件です。
MCP_MAX_CONCURRENT_REQUESTS / MCP_MAX_QUEUED_REQUESTS	リクエスト受付の上限です。デフォルトは、実行中 8 件、キュー内 16 件です。
MCP_REQUEST_INGRESS_TIMEOUT_MS	受付キューでの待機とリクエスト本文のアップロードを合わせた絶対上限です。ツールの実行時間は含まれません。デフォルト：10000、最大：60000。
MCP_REQUEST_EXECUTION_TIMEOUT_MS	アップロード後のツール実行に対する絶対上限です。デフォルト：90000、最大：180000（0.1.2 より前は 300000。これを超える値を設定すると、現在は起動が停止します）。HTTP のアイドルタイムアウトは、これら両方の上限に従います。

サーバーは、MCP_AUTH_TOKEN と MCP_ALLOWED_HOSTS が設定されていない場合、ループバック以外のアドレスへのバインドを拒否します。また、MCP_AUTH_TOKEN と MCP_REQUEST_STATE_KEY の両方がない場合、書き込みの有効化を拒否します。MCP_AUTH_TOKEN を設定すると、ループバックでも、すべての /mcp リクエストにそのベアラートークンが必要です。Host と Origin のチェックは、MCP ハンドラーより先に実行されます。

openssl rand -hex 32 を 2 回実行して、MCP_AUTH_TOKEN と MCP_REQUEST_STATE_KEY にそれぞれ独立した値を生成してください。Livespace の認証情報を再利用しないでください。

Bun プロセスは TLS を終端しません。ネットワークに公開するすべてのデプロイメントの前段に、TLS 対応のリバースプロキシを配置してください。サーバーは環境変数から認証情報を読み込みます。通常は Bun の .env 読み込み機能を使用します。.env ファイルを保存時に保護する責任は運用者にあります。絶対にコミットしないでください。スモークテスト用スクリプトでは、macOS キーチェーンからサンドボックスの認証情報を読み込むこともできます。

書き込みの安全性

通常のフローでは、まず確認を行います。

1. dryRun: true を指定すると、書き込みや承認要求を行わずに計画を作成します。
2. フォームによる確認に対応したクライアントでは、dryRun: true を指定せずに呼び出すと、実行前に人間に計画の承認を求めます。confirm: true 引数を指定しても、この確認を回避することはできません。
3. 確認のやり取りでは、5 分間有効で、承認または拒否の応答後に消費される署名付き requestState を使用します。存在する場合は認証済みプリンシパルに加え、ツール、引数、プレビューに紐付けられます。
4. 承認前に該当レコードが変更されていた場合、ツールは recordsChanged: true を返し、何も書き込まず、新しい計画を提示します。

フォームによる確認に対応していないクライアントでは、書き込みの実行はデフォルトで無効です。これらのクライアントではプレビューできますが、confirm: true は拒否されます。互換性のため、オペレーターは MCP_ALLOW_UNBOUND_WRITE_CONFIRMATION=true を設定できます。このモードでは、人間がプレビューを確認したことを示す署名付きの証明なしに、confirm: true で実行されます。

結果では、次のケースが区別されます。

• verification: verified は、書き込み後にサーバーが比較可能なフィールドを再読み込みしたことを意味します。
• 書き込みが成功していても、後続の読み取りに失敗した場合、送信されたフィールドに独立した比較対象がない場合、または上流 API が読み戻しに対応していない場合は、verification: unavailable と報告されることがあります。その項目のエラーを確認し、可能であればレコードを再読み込みしてください。書き込みを再試行しないでください。
• unknown_outcome は、リクエストが反映された可能性も、反映されていない可能性もあることを意味します。確認せずに再試行しないでください。
• not_attempted は、その項目が送信されなかったことを意味します。通常は、時間予算が尽きた場合、または先行する項目で上流のレート制限に達した場合に発生します。送信されなかった項目は後から送信できます。レート制限に達した項目については、エラーのヒントに従ってください。

通知の成功は、配信済みではなく、送信処理済みとして報告されます。配信が重要な場合は、通知を重複して送信するのではなく、別のチャネルで確認してください。

セキュリティとプライバシー

CRM の名前、メモ、インポートしたメール、タスクのテキスト、ウォールの記載内容は信頼できないデータです。サーバーがこれらを指示として評価することはありませんが、その内容によって MCP ホストやモデルが影響を受ける可能性はあります。クライアントが人間による確認フローを提供しない限り、書き込みは無効にしてください。タスクに必要なレコードと詳細レベルのみを取得してください。

ツールの応答は、MCP ホスト、モデルプロバイダー、またはローカルクライアントのログに保持されることがあります。処理する CRM データに適したストレージ、トレーニング、保持ポリシーを持つホストを選んでください。このサーバーは CRM レコードをディスクに保存せず、テレメトリーも送信しませんが、結果を受信した後にホストが行うことは制御できません。

管理者のキーではなく、専用の Livespace API ユーザーを使用してください。そのユーザーには、必要最小限のレコード権限と書き込み権限を付与してください。業務データに接続する前に、別のテストアカウントで MCP を評価してください。

リバースプロキシを使用する場合は、TLS を終端し、キャッシュを無効にして、MCP のリクエストまたはレスポンス本文をログに記録しないでください。サーバーは Cache-Control: no-store と Vary: Authorization を設定しますが、プロキシのポリシーでもこれらの保護を維持する必要があります。

インシデント対応

Livespace キー、ベアラートークン、または確認キーが漏えいした可能性がある場合：

1. MCP サーバーを停止します。
2. 直ちに Livespace API キーを無効化し、専用 API ユーザー用の新しいキーを発行します。
3. 新しい独立した MCP_AUTH_TOKEN と MCP_REQUEST_STATE_KEY の値を生成します。
4. サーバーを再起動し、MCP クライアントの Bearer ヘッダーを更新します。
5. Livespace のレコード履歴とアクティビティ履歴を確認し、予期しない書き込みがないか調べます。以前に unknown_outcome を返した操作は再試行しないでください。

v1 の制限事項

• 削除操作とマージ操作はできません。
• v1 ではタグやカスタムフィールドへの書き込みはできません。Livespace ではタグの変更に tag_add と tag_remove、カスタムフィールドには dataset を使用すると説明されています。タグへの書き込みには、 これらの正確なキーを使ったサンドボックスでの検証がまだ必要です。カスタムフィールドへの書き込みは、 選択フィールドの回答 ID を含め、サポートされる型を網羅するフィールドがサンドボックスに用意されるまで 検証できません。
• ここで作成したタスクをレコードにリンクすることはできません。Livespace の Todo/addTodo のドキュメント では、todo.objects を使ってリンクすると説明されていますが、サンドボックスで検証したところ、 成功が返され、送信したリンクも応答に含まれていた一方、新たに読み取ると objects: [] が返されました。正確な生の検証ペイロードは保存されていないため、 結果は確定できません。リンクが永続化されることを制御された検証で確認するまで、 サーバーはタスクへの書き込み時に objects を省略します。Livespace が返す既存のリンクは、 引き続き linkedRecords として公開されます。
• 記録済みのメモと通話は編集または削除できません。
• 商談の更新では、名前とステータス（open、won、lost）を変更できます。ステージの変更には move_deals_to_stage を使用します。create_records では商談の作成時に予算項目を設定できますが、 追加と置換のどちらの動作になるかが確認されていないため、update_records では既存の予算を編集できません。
• stage_conversion は、Livespace がステージ履歴を公開していないため、ある時点での推定値です。
• 読み取りと分析には上限付きの期間が使用されます。結果が完全なものとして扱う前に、 切り捨てを示すフィールドを確認してください。
• 値が欠落している場合や通貨が混在している場合、金額の合計が null になることがあります。結果には その理由が示されます。
• API の ID は Livespace の UI に表示される ID とは異なります。crm_metadata、 search_crm、または別のツールから返される ID を使い、推測で指定しないでください。

開発

公開済みパッケージではなくソースから作業するには、次のとおりです。

git clone https://github.com/proAutomator/livespace-crm-mcp.git
cd livespace-crm-mcp
bun install
cp .env.example .env
bun run dev

リポジトリのコマンドは次のとおりです。

bun test                 # complete offline suite
bun run test:security    # focused security contract from docs/security.md
bun run typecheck
bun run smoke            # live test-account check via .env or macOS Keychain
bun run dev

bun run smoke と、checkLivespace: true を指定した health は実際の API 呼び出しを行います。 本番環境の CRM ではなく、テスト用の Livespace アカウントのみを使用してください。

このバインディングの脅威モデルと回帰テストの対応表は、 docs/security.md にあります。 脆弱性は SECURITY.md の記載に従って、非公開で報告してください。

免責事項

コミュニティプロジェクトです。Livespace S.A. とは提携しておらず、同社からの推奨やサポートも受けていません。 「Livespace」は所有者の商標であり、ここでは互換性を示す目的でのみ使用しています。Livespace API を通じた操作は、 お客様の API キーを使用して実行され、Livespace の利用規約に基づき、お客様の責任で行われます。

謝辞

このサーバーは、Adam Gospodarczyk（overment）の MCP サーバーのパターン、特に iceener/streamable-mcp-server-template （MIT）を参考にしています。意図に沿った小規模なツール群、操作手順、項目ごとの結果とエラーに復旧のヒントを含める、 バッチを優先した書き込みを取り入れています。Adam に感謝します。

作者

Kuba Masztalski が開発しました。

• LinkedIn：linkedin.com/in/kuba-masztalski
• X：@proAutomator

バグ報告や機能リクエスト： GitHub Issues。 セキュリティに関する報告：SECURITY.md を参照してください。

ライセンス

MIT