lgl-mcp-server

Little Green Light（LGL）MCP サーバー

Little Green Light CRM データベース向けの、直接接続できる安全で忠実度の高い Model Context Protocol（MCP）サーバーです。このサーバーを使うと、AI コーディングアシスタントやチャットアプリケーション（Claude Desktop、LibreChat、Open WebUI など）から、サードパーティのミドルウェア（Zapier など）を介さずにローカルでドナーデータベースを安全に操作し、関係者の検索、寄付の記録、分類グループのカテゴリ分け、レポートの生成を行えます。

---

機能

• 構成員とコア情報の管理： 構成員レコードの検索、取得、作成、更新、削除ができます。create_constituent は、完全に空欄の本人情報（organization_name、または first_name／last_name のいずれかが必要）の場合、空のレコードを黙って作成するのではなく、拒否します。集計レポート（top_donors など）のラベル付けに使われる一括名前解決ヘルパーは、「構成員が存在しない」場合と、それ以外の検索失敗（レート制限、ネットワーク、認証）を区別し、どちらも同じ代替処理で覆い隠すことはありません。
• 高度なサーバーサイド検索： search_constituents_advanced は、LGL 独自のクエリエンジンを通じて構成員を直接絞り込みます。カスタム属性（含む／一致／前方一致／空欄／空欄以外）、キーワード、所在地、会員ステータス／レベル、グループ、リスト、更新日で絞り込み、すべてを AND 条件で組み合わせます。内部的な LGL ID ではなく、わかりやすい表示名を使って参照します。属性値は明示的に要求された場合（include_custom_attrs）にのみ結果に含まれるため、通常の絞り込み検索は軽量です。constituents_never_touched_attribute は、指定したカスタム属性が一度も設定されたことのないレコードを検索します。これは、LGL 独自の空欄／空欄以外の演算子では「設定済みだが空」と区別できない状態です。constituents_missing_info は、最初のページだけでなく構成員リスト全体を走査して、メールアドレス、電話番号、住所のいずれかが欠けているレコードを検索します。また、limit でスライスした結果とは別に count を返し、アカウントの規模が大きく、基盤となるスキャンのページ上限に達した場合は truncated で示します。
• ファンドレイジングと寄付： 新しい寄付の記録、取引の一覧表示（日付範囲フィルター付き）、支払いの検索、キャンペーン、基金、寄付の呼びかけ、イベントの確認ができます。寄付／寄付者検索ツールは、各レコードの寄付種別と、誓約／分割払いとの関連情報を表示します。また、寄付総額レポートでは二重計上を避けるため、現金総額から誓約を除外します。詳しくは、以下の寄付種別と誓約の関連付けをご覧ください。
• 連絡先のサブリソース： 構成員の住所、電話番号、メールアドレス、ウェブアドレスをすべて管理できます。
• 活動とメモ： メモの記録、連絡報告の作成、ボランティア活動時間の追跡ができます。
• グループと会員資格： カスタマイズ可能なグループと会員レベルで構成員を整理できます。
• 一括寄付者検索： get_donor_context は、プロフィール、最近の寄付、グループへの所属、最近のメモを1回の呼び出しで返します（名前または ID で解決します）。
• プロフィールの完全エクスポート： export_constituent_profile は、LGL 独自の「Export Profile」ボタンと同等の機能です。完全なレコード、寄付履歴全体、関係、クラス／学校への所属、会員資格、ボランティア活動時間、連絡報告、寄付の呼びかけへのリクエスト、イベントへの招待、グループへの所属、メモを、1回の呼び出しで並行して取得します。
• ドキュメントリンク： log_document_link は、別の場所（OneDrive／SharePoint など）でホストされているファイルを指すメモを記録します。LGL の API にはファイルアップロード用エンドポイントがないため、これは実際の添付ファイルではなく参照リンクです。詳しくは、以下のAPI の制約と回避策をご覧ください。
• 保存済みリストとしてのグループ： create_group_with_members は、グループを作成して構成員を追加する処理を1回の呼び出しで実行します。作成／編集用のエンドポイントがない、LGL の UI でのみ使える動的リストに対する、API で実現可能な最も近い代替手段です。会員資格の書き込みは一度に20件ずつまとめて行われるため、大量の構成員リストで API に際限のない同時リクエストが送られることはありません。詳しくは、以下のAPI の制約と回避策をご覧ください。
• 3段階の権限レベル： 読み取り専用、支援付き（読み取り専用に加え、メモと人によるレビューを経る Webhook 書き込み）、フルの3種類です。詳しくは、以下の権限レベルをご覧ください。
• アクセス監査証跡： get_constituent、get_donor_context、export_constituent_profile が使用されると、自動的に記録されます。LGL_ACCESS_LOG_DESTINATION の設定に応じて、構成員の LGL レコードに [AI Access Log] メモとして記録するか、ローカルの Excel ファイルに行として記録します。詳しくは、以下のアクセス監査ログをご覧ください。
• 人によるレビューを経る書き込み： 5つの submit_*_for_review ツールは API ではなく、LGL 独自の Integration Queue Webhook に送信します。そのため、すべての書き込みは反映される前に LGL 上で人が承認します。フルモードと支援付きモードで利用できます。詳しくは、以下の人によるレビューを経る書き込み（Integration Queue）をご覧ください。
• ミドルウェアなしのアーキテクチャ： データはローカルの AI クライアントと LGL API の間を直接やり取りするため、セキュリティリスクとサードパーティ料金を抑えられます。

---

インストールとセットアップ

1. 前提条件

• Node.js（v18 以降を推奨）
• Little Green Light API Key（LGL アカウントの Settings > Integration > API Keys で生成します）

2. 依存関係のインストール

このリポジトリをローカルマシンにクローンし、フォルダー内でターミナルを開いて、次を実行します。

npm install

3. 環境変数の設定

.env.example テンプレートをコピーして、ローカルの .env 設定ファイルを作成します。

cp .env.example .env

テキストエディターで .env を開き、プレースホルダーを実際の LGL API キーと設定に置き換えます。

LGL_API_KEY=your_lgl_api_key_here
PORT=3000

# Optional: Secure your Streamable HTTP endpoint with Bearer Token Authentication
LGL_MCP_TOKEN=your_secure_bearer_token_here

# Optional: enables the submit_*_for_review tools — see "Human-Reviewed Writes" below
LGL_INTEGRATION_LISTENER_URL=https://your-account.littlegreenlight.com/integrations/your-integration-id/listener

# Optional: field-name casing for submit_*_for_review payloads — "snake"
# (default) or "title" — see "Human-Reviewed Writes" below
LGL_INTEGRATION_FIELD_CASE=snake

# Optional: choose where the automatic access-audit trail is logged —
# "lgl_note" (default) writes a note directly to LGL, "excel" appends a row
# to a local spreadsheet instead. See "Access Audit Logging" below.
LGL_ACCESS_LOG_DESTINATION=lgl_note

# Required only when LGL_ACCESS_LOG_DESTINATION=excel — absolute path to the
# .xlsx file to append access-log rows to.
LGL_ACCESS_LOG_PATH=C:\path\to\AI_Access_Log.xlsx

権限レベル

2 つの環境変数を組み合わせることで、3 つの権限レベルを設定できます。

レベル	LGL_READ_ONLY	LGL_ASSISTED_MODE	許可される操作
完全な読み取り専用	true	未設定／false	読み取りのみです。あらゆる書き込みが禁止されます。直接の変更やメモ（LGL_ACCESS_LOG_DESTINATION=lgl_note の場合の自動アクセス監査メモを含む）、Integration Queue への送信もできません。Excel のアクセス監査先（LGL_ACCESS_LOG_DESTINATION=excel）は LGL に一切アクセスしないため、このモードでもログを記録します。
アシスト	true	true	読み取り専用で許可されるすべての操作に加えて、リスクが低く、容易に確認できる書き込みが許可されます。自動アクセス監査メモ、明示的な create_note／update_note／log_document_link、および submit_*_for_review Integration Queue ツールが対象です。構成員／寄付／グループなどへの直接変更（create_group_with_members を含む）は引き続き禁止されます。
フル	未設定／false	（無視されます）	制限はありません。直接の create_*／update_*／delete_* による変更を含む、すべてのツールを使用できます。

# Strictly read-only
LGL_READ_ONLY=true

# Assisted: read-only plus notes and human-reviewed webhook writes
LGL_READ_ONLY=true
LGL_ASSISTED_MODE=true

読み取り専用モードとアシストモードでは、許可されていないツールは呼び出し時に拒否されるだけでなく、tools/list に表示されません。これにより、AI アシスタントがそれらのツールを使おうとするのを防ぎます。LGL_ASSISTED_MODE は LGL_READ_ONLY=true も設定されていないと効果がありません。フルモードでは、アシストモードで有効になる機能はすべてすでに利用可能です。稼働中の寄付者データベースにサーバーを接続する場合は、探索のみのセッションには完全な読み取り専用を、アクセス監査記録と人による確認を経た書き込みも行う場合はアシストモードを使用することを推奨します。

すべてのツールは MCP の annotations（readOnlyHint、destructiveHint、idempotentHint）も公開するため、クライアントはサーバー側のガードに依存せず、破壊的な呼び出しの前に警告できます。

---

アクセス監査ログ

get_constituent、get_donor_context、または export_constituent_profile が呼び出されるたびに、サーバーは監査目的でアクセスを記録します。ログの出力先は LGL_ACCESS_LOG_DESTINATION で制御します。

• lgl_note（デフォルト）： LGL の該当する寄付者のレコードに直接メモを書き込みます。例：[AI Access Log] Record accessed via LGL MCP Server (get_constituent) on 2026-07-13 17:24 UTC. ログは有効な権限レベルに従って記録されます。厳密な読み取り専用モードでは、LGL に一切変更を加えないことが目的のため、ログ記録は無言でスキップされます。
• excel： 代わりに、タイムスタンプ、ツール、寄付者 ID、寄付者名を含む行を、LGL_ACCESS_LOG_PATH に指定された .xlsx ファイルに追加します。LGL には一切書き込まないため、厳密な読み取り専用モードを含むすべてのモードで記録されます。

LGL の UI（Settings → Menu Items → Note Types）でメモの種類を無効にしても、その種類の既存のメモは寄付者のアクティビティビューに表示されたままです。また、API は無効にした種類の ID を使って新しいメモを書き込むこともできます。そのため、lgl_note のログ記録に使うメモの種類を無効にしても、表示がすっきりするわけではありません。その種類がスタッフ向けの手動の「新しいメモ」ドロップダウンに表示されなくなるだけです。寄付者レコードにメモが増えることが懸念される場合は、代わりに excel に切り替えてください。

知っておくとよい点をいくつか紹介します。

• 対象は単一レコードの詳細ビューのみです。 一括の list_*／search_* 呼び出しでは記録されません。50 件のリストのすべての行を記録すると、監査上の価値がほとんどないままログが膨大になるためです。特定の寄付者のファイルを開くツールのみが対象です。
• どちらの出力先もベストエフォートです。 ログエントリの書き込みに何らかの理由で失敗しても、そのきっかけとなった読み取りは成功します。失敗は標準エラー出力に記録され、ツールエラーとして表面化することはありません。excel の場合、ファイルがロックされている（たとえば Excel で開いている）ときは、諦める前に数回再試行します。
• lgl_note は Integration Queue を介さず、API 経由で直接書き込みます。 表示に人の承認が必要な監査証跡では、目的を果たせないためです。また、メモの種類の名前ではなく、既存の note_type_id（数値）が必要です。名前を渡しても、LGL は適用せず無言で無視します。アカウントごとに種類の ID が異なるため、ID をハードコードするのではなく、サーバーは実行時に種類を解決します（名前が文字どおり「General」の種類を優先し、なければ存在する最初の種類を使用します）。この修正は create_note／update_note にも適用されます。これらは以前、実際には適用されない note_type 文字列を受け付けていましたが、無効な種類名を指定すると、種類のないメモを無言で作成する代わりに、明確なエラーが発生するようになりました。
• excel はファイルが存在しない場合に作成します。 太字で固定されたヘッダー行（Timestamp、Tool、Constituent ID、Constituent Name）が追加され、ファイルは際限なく増え続けます。自動ローテーションやアーカイブはありません。
• excel は高い同時実行負荷には安全ではありません。 書き込みのたびにロックなしでファイル全体を読み込んで書き直すため、まったく同時に発生した 2 件のアクセスが競合し、一方の行が無言で上書きされる可能性があります。これはベストエフォートの監査ログとして許容しているトレードオフです。一般的な単一クライアントでの使用では問題にならない見込みですが、同じファイルに対して複数の MCP セッションから並行して記録する場合は注意してください。

---

人による確認を経る書き込み（Integration Queue）

LGL には、直接の LGL API とは別に、フラットなキーと値の送信を受け付け、データが寄付者の記録に実際に書き込まれる前に人が承認できるよう、Integration Queue に格納するカスタム統合ウェブフック機能もあります（LGL Settings → Integrations → Custom Integrations）。このサーバーでは、この経路を create_*／update_* API ツールとは別の、次の 5 つのツールとして公開しています。

ツール	対応する内容
submit_constituent_for_review	身元・氏名のフィールド、電話番号最大 3 件、メールアドレス最大 3 件、郵送先住所最大 2 件、ウェブサイト、寄付者カテゴリのフィールド、および関係
submit_gift_for_review	寄付、誓約、目標のフィールド、およびトリビュート（顕彰／追悼）の詳細。gift_type は LGL の実際の寄付タイプに制限されています（寄付タイプと誓約の関連付けを参照）
submit_note_for_review	メモ
submit_event_registration_for_review	イベントの登録／招待
submit_appeal_request_for_review	アピールの依頼

これら 5 つのツールはいずれも、LGL に直接書き込みません。すべての送信内容は LGL の Settings → Integration Queue → Unsaved に格納され、担当者が確認して保存または却下します。そのため、完全な書き込みアクセスではなく、支援モードだけで利用できます。LGL_READ_ONLY=true と LGL_ASSISTED_MODE=true を設定すれば十分です。LGL で人が「Save」をクリックしない限り、これらのツールでデータを変更できないためです。ただし、厳密な読み取り専用モード（LGL_ASSISTED_MODE を設定しない場合）では、共有キューへの実際の書き込みであるため、引き続き利用できません。

セットアップ：

1. LGL で Settings → Integrations に移動し、カスタム統合を作成（または既存のものを再利用）します。リスナー URL をコピーします。
2. 環境で LGL_INTEGRATION_LISTENER_URL にその URL を設定します。
3. 該当する統合のフィールドマッピング画面で、送信時に使用するフィールド名を対応する LGL フィールドにマッピングします。マッピングはすべて LGL の UI 内で行われ、このサーバーでは行われません。マッピングされていないフィールドはエラーにならず、LGL によって黙って無視されるため、マッピングされていない送信でも、利用可能なデータが含まれていないまま成功したように見える（HTTP 200）場合があります。繰り返し使用するフィールド（電話／メール／住所）は LGL の「Record Type / #」グループ分けを使用します。スロット 1 はフィールド名そのもの、スロット 2～3 は数値の接尾辞を使います（phone_2、email_3）。
4. このサーバーが送信するフィールド名の大文字・小文字の形式は、LGL_INTEGRATION_FIELD_CASE で制御される次の 2 種類のいずれかです。"snake"（デフォルト。例：first_name、phone、gift_amount）または "title"（例：First name、Phone number、Gift amount。index.js の検索テーブルを介して変換されます）。実際のマッピング画面で使用している形式に合わせてください。生の引数名に直接マッピングしているアカウントもあれば、LGL 独自のタイトルケースのフィールドラベルに合わせてマッピングを再設定しているアカウントもあります。標準のままでマッピングが一致する LGL アカウントはないため、いずれのツールを使用する場合も、事前に自分のマッピング画面で確認してください。

既存の寄付者との照合： 5 つのツールすべてで、LGL の寄付者 ID を指定するオプションの record_id フィールドを使用できます。これは推奨される照合キーですが、機能するのは、統合の設定にあるレコード照合の優先設定（フィールドマッピングと同じ場所）で ID ベースの照合が設定されている場合に限られます。デフォルトのメールアドレス／名前ベースの優先設定では、「LGL constituent ID」フィールドをマッピングしても照合結果は保持されません。record_id が省略された場合、または統合がメールアドレス／名前ベースの照合設定のままの場合、LGL は first_name + last_name + email で照合します。

---

スキーマの値制約

いくつかの submit_*_for_review フィールドは、LGL 自体が定義する固定された選択肢のセットを表しているため、ツールスキーマでは説明文を添えた自由入力フィールドではなく、実際の JSON Schema enum を使用しています。これにより、AI クライアントは推測するのではなく、有効な値に制限されます。対象は、constituent_type、deceased、gives_anonymously（submit_constituent_for_review）、payment_interval、gift_is_anonymous、auto_generate_installments、gift_type（submit_gift_for_review。以下のギフトの種類と誓約の関連付けを参照）、attended、rsvp_status、is_guest（submit_event_registration_for_review）、appeal_status（submit_appeal_request_for_review）です。

一方、address_type、phone_type、email_type、web_address_type、contact_type、relationship_type は、LGL で実際にアカウントごとにカスタマイズ可能な値のリストであり、プラットフォーム全体で固定された列挙値ではありません。これはこのアカウントで実際に確認済みです。たとえば、実際の連絡先の種類（Call／Meeting／Mailing／Proposal／Tour）は、一般的な例とは一致しません。これらは自由入力のままですが、送信前にアカウント固有の実際の値を確認できるよう、説明から list_type_values（対応する type キーは street_address_types、phone_number_types、email_address_types、web_address_types、contact_report_types）または list_relationship_types を参照するよう案内しています。

---

ページネーションと切り捨ての通知

上限のないレコード集合を一覧表示または検索するいくつかのツールでは、一部のページだけをすべての結果であるかのように黙って返すのではなく、結果が不完全である可能性を通知するようになりました。

• アカウント全体の一覧 — list_campaigns、list_funds、list_events、list_appeals、list_groups、list_categories — 固定の limit=200 を指定した単一の呼び出しではなく、データセット全体（最大 5,000 件）を取得します。上限に達しない限り、従来どおり通常の配列を返します。上限に達した場合は { count, <items>, truncated: true } を返すため、不完全な結果を完全なものと誤認することはありません。同じ根本的な修正は、以前は古い 200 件の上限より後にある実在の値を「存在しない」と誤って報告していた、内部の名前ベースの検索（グループ、カスタム属性、リスト、会員レベル、キーワードを名前で解決する処理）にも適用されます。
• search_contact_reports、search_volunteer_times、およびスコープ指定のない（constituent_id を指定しない）list_notes／list_contact_reports／list_volunteer_times モード — limit パラメーターを受け取り、ページがちょうど上限件数で返された場合にその旨を通知します（実際の件数が偶然上限と一致する可能性があるため、これは保証ではなくヒューリスティックです）。その場合、レスポンスは { count, results, note } となり、limit を増やすか、クエリを絞り込むよう促します。

別件： search_contact_reports と search_volunteer_times は、以前はクエリに関係なく、すべての呼び出しで 400 エラーを返していました。これは既存のバグで、上記の機能とは無関係ですが、テスト中に発見されました。原因は、以下で説明する /constituents/search の問題と同じです。LGL は単独の q=value を拒否し、q[]=field=value を要求します。この形式を使うよう修正しました（フィールドは text／description で、create_contact_report／create_volunteer_time が既に書き込んでいるフィールドと一致します）。連絡先レポートでは実際に動作することを確認済みです。ボランティア時間の検索でもエラーは発生しなくなりましたが、このアカウントにはボランティア時間のレコードがないため、フィールド名までは完全に確認できていません。

---

ギフトの種類と誓約の紐づけ

LGLでは、誓約、マッチングギフト、分割払いは別々のオブジェクト型ではありません。これらはすべて Gift レコードであり、gift_type_name／gift_category_name の組み合わせで区別されます。また、支払いは parent_gift_id を介して支払い対象に紐づけられます。生の API 出力のままでは、この点を誤解しやすくなります（誓約を示す parent_gift_id が設定されていると知らなければ、分割払いの支払いは無関係な少額のギフトに見えます）。このサーバーでは、この違いを明示的に示します。

• list_gifts、get_gift、get_donor_context、export_constituent_profile にはすべて、type フィールド（gift_type_name 由来）が含まれます。また、LGLから提供される場合は gift_category_name と parent_gift_id も含まれます。get_gift では、type を数十のフィールドの中に埋もれさせず、レスポンスの最上位にも配置します。
• LGLのネストされた /constituents/{id}/gifts リストエンドポイントでは、一部のレコードについてこれらのフィールドが省略されます。その場合、これらのツールはレコードごとに追加の呼び出しを行って値を補完します（1リクエストあたり最大50レコード）。
• submit_gift_for_review の gift_type フィールドには、LGLで実際に使用されるギフトの種類（list_gift_types から取得）を指定します。指定できるのは Gift、In Kind、Pledge、Other Income、In Honor of、In Memory of、Soft Credit、Matching、Installment です。分割払いの支払いには誓約のギフト ID を指定し、LGLで正しく紐づけられるようにしてください。
• record_gift／update_gift（上記の Integration Queue 経由とは異なる、直接書き込みを行う API ツール）でも、gift_type（同じ列挙値）と parent_gift_id を指定できるようになりました。以前は gift_type フィールドがなく、これらのツールで記録したギフトはすべて、気づかないうちに通常の Gift になっていました。そのため、誓約を記録したり、分割払いを誓約に紐づけたりする方法がなく、書き込み側から上記の二重計上の問題を再発させる状態でした。
• 誓約の二重計上： 誓約レコードには請求額の全額が記録され、分割払いの支払いにはそれぞれの金額も加算されます。両方を合計すると、同じ金額を二重に数えることになります。このため、recent_donors、top_donors、lapsed_donors では、寄付総額の集計から Pledge と Soft Credit のレコードを除外します（実データで確認済みです。50万ドルの誓約と、それに対する10万ドルの分割払い5件を合計すると、除外しない場合、寄付者の報告総額が100万ドル以上に膨らみます）。list_gifts／get_gift／get_donor_context／export_constituent_profile では引き続き誓約レコード自体を返します。除外の対象は、上記3つの集計レポートツールに限られます。

---

API の制約と回避策

LGL 独自の Web UI がサポートしていても、LGL の API には相当する機能がまったくないものがあります。REST API にも、Integration Queue webhook にもありません（この webhook が受け付けるのは、寄付者／寄付／メモ／イベント登録／寄付申込の各フィールドのみです）。執筆時点で、以下の機能がないことを確認しています。

UI の機能	API エンドポイントはありますか？	Webhook のフィールドマッピングはありますか？	このサーバーの対応方法
チームメンバーに割り当てられるタスク／ToDo／リマインダー	いいえ	いいえ	ありません。LGL のタスク機能（リマインダーメールを含む）にプログラムからアクセスする方法はありません。今後の唯一の手段は、LGL Support への正式な機能リクエストです。
寄付者レコードへのファイル／ドキュメントの添付	いいえ	いいえ	log_document_link は、別の場所（OneDrive、SharePoint、Google Drive など）でホストされているファイルへのリンクと説明を含むメモを記録します。これは参照であり、実際の添付ファイルではありません。LGL は API 経由でアップロードされたファイルを受け付けることができず、LGL 独自の Web フォームでもホストされた URL のみが受け付けられ、生のファイルデータは受け付けられません。
保存済みリスト（動的に再実行可能なクエリ）	いいえ（少なくとも読み取り専用です）	いいえ	create_group_with_members は、LGL のグループ（寄付者の固定された集合）を作成し、1 回の呼び出しでメンバーを追加します。グループは API から完全に書き込み可能で、「後から参照する人々の集合」という似た用途に使えますが、メンバーシップは固定されており、ライブクエリではありません。その後、add_constituent_to_group／remove_constituent_from_group でメンバーを追加／削除できます。
プレッジの分割払いの期日／予定日	いいえ	いいえ	実際のレコードで確認済みです。未払いの分割払いの寄付には、API レスポンスに gift_date、due_date、その他のスケジュールフィールドがありません。あるのは received_date だけで、支払いが実際に受領されるまで null のままです。プレッジレコード自体も、GET では payment_interval／pledge_start_date が公開されないため、クライアント側で予定期日を算出する方法もありません。list_gifts／get_gift でこれらが date: null と表示されるのは、LGL の API が実際に返す情報がそれだけだからです。スケジュールは UI のみで扱われ、API では公開されていないようです。

---

トランスポートの選択

このサーバーは、2 つの通信トランスポート規格をサポートしています。

• Stdio トランスポート（デフォルト）： 標準入力／出力プロセスチャネルです。Claude Desktop などのローカルプログラムや、ローカルのコマンド設定に適しています。
• Streamable HTTP トランスポート（SSE）： HTTP 上で最新のステートフルな Server-Sent Events（SSE）を提供するネイティブ HTTP サーバーを実行します。GitHub Copilot、Cursor の SSE モード、クラウドコンテナ、およびローカルの Node.js プロセスをネイティブに実行しないシステムで必要です。

Streamable HTTP モードでの実行

サーバーを Streamable HTTP モードで起動するには、--http（または --sse）フラグを使用します。

node index.js --http --port 3000

• ポートの選択： --port <number> または PORT 環境変数でカスタムポートを指定できます（デフォルトは 3000 です）。
• セキュアなトークン保護： .env ファイルで LGL_MCP_TOKEN を設定すると、Bearer トークン認証が厳密に適用されます。すべてのクライアントリクエストに Authorization: Bearer <your_token> ヘッダーを含める必要があり、含まれていない場合は 401 Unauthorized で拒否されます。設定しなくてもサーバーは起動しますが、認証は一切行われません。 起動時に見落としにくい警告がログに記録されますが、ポートに接続できる人なら誰でもリクエストを送信できます。トークンなしで実行するのは、localhost にバインドされている場合など、マシンの外部から接続できない場合に限ってください。

---

AI クライアントとの連携

このサーバーは、Model Context Protocol（MCP）をサポートするあらゆる AI クライアント、エディター、チャットインターフェースと連携できます。

1. Claude Desktop

公式の Claude Desktop アプリケーションでこのサーバーを使用するには、claude_desktop_config.json ファイルに設定を追加します。

ファイルの場所：

• Windows： %APPDATA%\Claude\claude_desktop_config.json
• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json

設定：

{
  "mcpServers": {
    "lgl-crm": {
      "command": "node",
      "args": ["C:\\path\\to\\your\\workspace\\folder\\index.js"],
      "env": {
        "LGL_API_KEY": "your_lgl_api_key_here"
      }
    }
  }
}

2. Cursor IDE（AI コードエディター）

Cursor は、グラフィカルユーザーインターフェースからカスタム MCP サーバーを直接サポートします。Stdio（コマンド）または Streamable HTTP（SSE）のいずれかを使用して接続できます。

オプション A：ローカル Stdio（コマンド）

1. Cursor を開き、Settings > Features > MCP に移動します。
2. + Add New MCP Server をクリックします。
3. ポップアップで各フィールドを設定します。
   • Name: lgl-crm
   • Type: command
   • Command: node C:\path\to\your\workspace\folder\index.js
4. Save をクリックします。注：Cursor が環境変数を継承できるよう、オペレーティングシステムの環境変数またはシェル設定で LGL_API_KEY が設定されていることを確認してください。

オプション B：Streamable HTTP（SSE モード）

1. LGL MCP サーバーを HTTP モードで起動します：node index.js --http --port 3000
2. Settings > Features > MCP に移動します。
3. + Add New MCP Server をクリックします。
4. ポップアップで各フィールドを設定します。
   • Name: lgl-crm-sse
   • Type: sse
   • URL: http://localhost:3000/mcp
5. Save をクリックします。注：LGL_MCP_TOKEN が有効な場合は、エディターに Bearer 認証ヘッダーまたは接続設定が含まれていることを確認してください。

3. Windsurf IDE（AI コードエディター）

Windsurf は、グローバル設定ファイルを使用したネイティブ MCP 設定に対応しています。

ファイルの場所：

• Windows： %USERPROFILE%\.codeium\windsurf\mcp_config.json
• macOS/Linux： ~/.codeium/windsurf/mcp_config.json

設定：

{
  "mcpServers": {
    "lgl-crm": {
      "command": "node",
      "args": ["C:\\path\\to\\your\\workspace\\folder\\index.js"],
      "env": {
        "LGL_API_KEY": "your_lgl_api_key_here"
      }
    }
  }
}

4. LibreChat（オープンソースのチャット UI）

LibreChat では、集中管理用の設定ファイル librechat.yaml を通じて MCP サーバーを直接統合できます。

librechat.yaml での設定：

mcpServers:
  lgl-crm:
    type: "stdio"
    command: "node"
    args: ["C:\\path\\to\\your\\workspace\\folder\\index.js"]
    env:
      LGL_API_KEY: "your_lgl_api_key_here"

5. Open WebUI（ローカル／セルフホスト型 AI UI）

Open WebUI（ローカルの Ollama インスタンスでよく使用されます）に追加するには、次の手順に従います。

1. Admin Settings > Connections > MCP に移動します。
2. Add Connection をクリックします。
3. 接続名に lgl-crm を入力します。
4. コマンドの設定を入力します。
   • Command: node C:\path\to\your\workspace\folder\index.js
5. Submit をクリックします。（Open WebUI インスタンスを実行しているホストマシンまたは docker run ステートメントで環境変数 LGL_API_KEY が読み込まれていることを確認してください。）

---

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

機密性の高い寄付者情報をサードパーティサービス（Zapier や Make など）経由で送信する他の MCP 統合とは異なり、このサーバーはローカルから直接接続するパイプラインで動作します。

• サードパーティによる保存はゼロ： すべての構成員データ、住所、メールアドレス、電話番号、寄付金の情報は、お使いのコンピューターから安全に暗号化された HTTPS 経由で公式 LGL API に直接送信されます。
• 最小権限の原則： デプロイ前に index.js ファイル内の該当するツールをコメントアウトまたは削除することで、データベースの変更（レコードの削除など）へのアクセスを簡単に制限できます。

---

ライセンス

このプロジェクトはオープンソースで、MIT License のもと、非営利団体が自由に改変して利用できます。