boostu-teamleader-mcp

🔗 BoostU Teamleader MCP

オープンソースの Teamleader Focus MCP サーバーです。Claude やその他の AI アシスタントから、自然な言葉で CRM を管理できます。🤖

---

💡 これは何ですか？

boostu-teamleader-mcp は、Teamleader Focus API を AI アシスタント（Claude Desktop、Claude Code、Cursor、Windsurf など）に公開する Model Context Protocol サーバーです。Teamleader Focus の全領域を網羅する 100 種類以上のツールを提供します。CRM（連絡先、企業、商談）、営業文書（見積書、請求書、クレジットノート）、製品カタログ、サブスクリプション、プロジェクト、時間管理、カスタマーサービスのチケットなどに対応しています。AI を接続するだけで、自然な言葉で CRM 全体を管理できます。

セルフホストを希望しませんか？

teamleader-mcp.boostu.be で、常時稼働のマネージド版をご利用ください。OAuth の設定は不要で、マジックリンクでログインでき、Claude 用のコネクターもワンクリックで設定できます。プレビュー期間中は無料で、その後は有料プランとなります。

このリポジトリは、オープンソースの MCP サーバーそのものです。ご自身の Teamleader 統合を使ってローカルで実行できます。ホスト版では、同じサーバーをベースに、マルチテナント認証、ダッシュボード、使用状況の分析、トークン管理機能を追加しています。

	セルフホスト（このリポジトリ）	マネージド（boostu.be）
価格	無料、MIT ライセンス	プレビュー期間中は無料、その後は有料
設定	独自の Teamleader 統合を作成し、npx で実行	コネクター URL を 1 つ Claude にコピー
トークン	.env とリフレッシュトークンを自分で管理	暗号化され、自動でローテーション
おすすめの対象	開発者やセルフホストを利用する方	技術的な知識を必要としないチーム

---

🔌 仕組み

flowchart LR
    U["🧑 You"] -->|"plain language"| C["🤖 Claude / AI assistant"]
    C <-->|"MCP · stdio"| S["🔗 boostu-teamleader-mcp"]
    S <-->|"OAuth2 REST"| T["📇 Teamleader Focus API"]

Claude に自然な言葉で依頼します。Claude はこの MCP サーバーを呼び出し、OAuth2 で Teamleader Focus に認証して、該当する API 呼び出しを実行します。データは Teamleader に保管されたままで、このサーバーは呼び出しを仲介するだけです。

このファイルの右上にあるアウトラインボタンを使うと、任意のセクションに移動できます。

---

✨ 主な特長

• 👥 CRM 全般：すべてのパイプラインにわたって、連絡先、企業、商談を作成・更新できます
• 🧾 見積書と請求：商談の見積書を作成し、請求書を会計に登録してメールで送信し、支払いを記録できます
• 📦 製品カタログ：製品、カテゴリー、価格表、単位を閲覧できます
• 🔁 サブスクリプション：定期サブスクリプションを作成、更新、無効化できます
• 📊 プロジェクトと時間管理：プロジェクトやマイルストーンを管理し、作業時間を記録して、リアルタイムタイマーを開始・停止できます
• 🎫 カスタマーサービスのチケット：チケットを作成し、返信を投稿して、ステータスを更新できます
• 🔎 参照データの検索：商談フェーズ、パイプライン、税率、支払い条件、失注理由などを検索できます
• 🔐 自動リフレッシュトークンローテーション対応の OAuth2：トークンは自動的に更新され、ローテーション後のトークンは設定可能なファイルに保存されます
• 🧩 ツールグループの選択：TEAMLEADER_TOOLS で必要なグループだけを読み込み、アシスタントのコンテキストをすっきり保てます

---

🚀 クイックスタート

インストールせずに実行

npx boostu-teamleader-mcp

グローバルインストール

npm i -g boostu-teamleader-mcp
boostu-teamleader-mcp

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json（macOS）または %APPDATA%\Claude\claude_desktop_config.json（Windows）に追加します。

{
  "mcpServers": {
    "teamleader": {
      "command": "npx",
      "args": ["-y", "boostu-teamleader-mcp"],
      "env": {
        "TEAMLEADER_CLIENT_ID": "your-client-id",
        "TEAMLEADER_CLIENT_SECRET": "your-client-secret",
        "TEAMLEADER_REFRESH_TOKEN": "your-refresh-token"
      }
    }
  }
}

Claude Code

プロジェクトの .mcp.json または ~/.claude/mcp.json に追加します。

{
  "mcpServers": {
    "teamleader": {
      "command": "npx",
      "args": ["-y", "boostu-teamleader-mcp"],
      "env": {
        "TEAMLEADER_CLIENT_ID": "your-client-id",
        "TEAMLEADER_CLIENT_SECRET": "your-client-secret",
        "TEAMLEADER_REFRESH_TOKEN": "your-refresh-token"
      }
    }
  }
}

Cursor

プロジェクトのルートにある .cursor/mcp.json（またはグローバルの ~/.cursor/mcp.json）に追加します。

{
  "mcpServers": {
    "teamleader": {
      "command": "npx",
      "args": ["-y", "boostu-teamleader-mcp"],
      "env": {
        "TEAMLEADER_CLIENT_ID": "your-client-id",
        "TEAMLEADER_CLIENT_SECRET": "your-client-secret",
        "TEAMLEADER_REFRESH_TOKEN": "your-refresh-token"
      }
    }
  }
}

Windsurf

~/.codeium/windsurf/mcp_config.json に追加します。

{
  "mcpServers": {
    "teamleader": {
      "command": "npx",
      "args": ["-y", "boostu-teamleader-mcp"],
      "env": {
        "TEAMLEADER_CLIENT_ID": "your-client-id",
        "TEAMLEADER_CLIENT_SECRET": "your-client-secret",
        "TEAMLEADER_REFRESH_TOKEN": "your-refresh-token"
      }
    }
  }
}

---

🔐 認証

3 つの環境変数 TEAMLEADER_CLIENT_ID、TEAMLEADER_CLIENT_SECRET、TEAMLEADER_REFRESH_TOKEN が必要です。Teamleader Marketplace / Developer portal でインテグレーションを登録し、OAuth2 認証フローを完了すると取得できます。

Teamleader は API 呼び出しのたびにリフレッシュトークンをローテーションします。サーバーが再起動後も最新のトークンを保持できるよう、書き込み可能なファイルパスを TEAMLEADER_TOKEN_STORE に設定してください。設定しないと、設定ファイル内のトークンは最初の再起動後に無効になります。

手順をすべて説明したガイド（認証 URL、コード交換、ヘルパースクリプト）については、docs/AUTHENTICATION.md をご覧ください。

---

⚙️ 設定

環境変数

名前	必須	説明
TEAMLEADER_CLIENT_ID	はい	Teamleader インテグレーションの OAuth2 クライアント ID
TEAMLEADER_CLIENT_SECRET	はい	Teamleader インテグレーションの OAuth2 クライアントシークレット
TEAMLEADER_REFRESH_TOKEN	はい	OAuth2 認証フローで取得した初期リフレッシュトークン
TEAMLEADER_TOKEN_STORE	いいえ	サーバーがローテーションされたリフレッシュトークンを保存する、書き込み可能なファイルへのパス（例：/var/run/teamleader-token）。本番環境では強く推奨します。
TEAMLEADER_TOOLS	いいえ	有効にするツールグループキーをカンマ区切りで指定します。未設定の場合、21 個すべてのグループが読み込まれます。

ツールグループの選択

TEAMLEADER_TOOLS を使用して、登録するツールグループを制限します。アシスタントのツール一覧を小さく保ちたい場合や、Teamleader の特定の領域へのアクセスを制限したい場合に便利です。

TEAMLEADER_TOOLS=deals,quotations,products

グループキーの一覧：

キー	対象
contacts	連絡先の CRUD
companies	会社の CRUD
deals	案件／商談
tasks	タスク
events	カレンダーイベント
invoices	請求書（作成、記帳、送信、支払い、ダウンロード）
quotations	見積書（作成、更新、送信、承認）
products	製品カタログと価格表
reference	案件フェーズ、税率、支払条件など
org	ユーザー、チーム、部門
customFields	カスタムフィールドの定義
creditNotes	クレジットノート
subscriptions	定期購読
projects	プロジェクトとマイルストーン
timeTracking	作業時間の記録と稼働中のタイマー
activities	電話とミーティング
tickets	サポートチケット
tags	連絡先や会社へのタグの追加／削除
notes	あらゆる対象に関するメモ
files	ファイル一覧、ダウンロード、アップロード
webhooks	Webhook の登録

---

🧰 利用可能なツール

連絡先

ツール	説明
teamleader_list_contacts	Teamleader Focus の連絡先を、任意のフィルタリングとページネーションを指定して一覧表示します
teamleader_get_contact	特定の連絡先の詳細情報を取得します
teamleader_create_contact	Teamleader Focus に新しい連絡先を作成します
teamleader_update_contact	Teamleader Focus の既存の連絡先を更新します
teamleader_link_contact_to_company	任意で役職と意思決定者フラグを指定して、連絡先を会社に紐付けます
teamleader_unlink_contact_from_company	Teamleader Focus の会社から連絡先の紐付けを解除します
teamleader_update_contact_company_link	既存の連絡先と会社の紐付けにある役職または意思決定者フラグを更新します

会社

ツール	説明
teamleader_list_companies	Teamleader Focus の会社を、必要に応じてフィルタリングやページネーションを指定して一覧表示します
teamleader_get_company	特定の会社の詳細情報を取得します
teamleader_create_company	Teamleader Focus に新しい会社を作成します

取引

ツール	説明
teamleader_list_deals	Teamleader Focus の取引／商談を、必要に応じてフィルタリングやページネーションを指定して一覧表示します
teamleader_get_deal	特定の取引の詳細情報を取得します
teamleader_create_deal	Teamleader Focus に新しい取引／商談を作成します
teamleader_update_deal	Teamleader Focus の既存の取引を更新します

タスク

ツール	説明
teamleader_list_tasks	Teamleader Focus のタスクを、必要に応じてフィルタリングやページネーションを指定して一覧表示します
teamleader_create_task	Teamleader Focus に新しいタスクを作成します

イベント

ツール	説明
teamleader_list_events	Teamleader Focus のカレンダーイベントを、必要に応じてフィルタリングやページネーションを指定して一覧表示します
teamleader_get_event	特定のイベントの詳細情報を取得します
teamleader_create_event	Teamleader Focus に新しいカレンダーイベントを作成します

請求書

ツール	説明
teamleader_list_invoices	Teamleader Focus の請求書を、必要に応じてフィルタリングやページネーションを指定して一覧表示します
teamleader_get_invoice	特定の請求書の詳細情報を取得します
teamleader_create_invoice	Teamleader Focus に新しい請求書の下書きを作成します
teamleader_invoices_book	請求書の下書きを会計処理に登録し、番号を割り当てます
teamleader_invoices_send	指定した宛先に請求書をメールで送信します
teamleader_invoices_register_payment	請求書に対する支払いを登録します
teamleader_invoices_download	指定した形式の請求書をダウンロードするための一時 URL を取得します

見積書

ツール	説明
teamleader_quotations_list	見積書を一覧表示します。必要に応じて取引 ID でフィルタリングできます
teamleader_quotations_info	ID で単一の見積書を取得します。必要に応じて有効期限（有効期限日）の設定も取得できます
teamleader_quotations_create	取引に見積書を作成します。明細項目やテキスト、名前、有効期限日を指定できます
teamleader_quotations_update	見積書を更新します。明細項目、テキスト、名前を変更したり、有効期限日を変更したりできます
teamleader_quotations_accept	見積書を承諾します（承諾済みとしてマークされます。元に戻すのは困難です）
teamleader_quotations_send	任意の件名とメッセージで見積書をメール送信します（cc、bcc、送信者、添付ファイル、言語を指定できます）。#LINK は署名リンクに置き換えられます

製品

ツール	説明
teamleader_products_list	製品を一覧表示します。必要に応じて検索語でフィルタリングできます
teamleader_products_info	ID で単一の製品を取得します
teamleader_product_categories_list	製品カテゴリを一覧表示します
teamleader_price_lists_list	価格表を一覧表示します
teamleader_units_of_measure_list	測定単位を一覧表示します

参照データ

ツール	説明
teamleader_deal_phases_list	取引フェーズを一覧表示します
teamleader_deal_pipelines_list	取引パイプラインを一覧表示します
teamleader_deal_sources_list	取引ソースを一覧表示します
teamleader_lost_reasons_list	取引の失注理由を一覧表示します
teamleader_tax_rates_list	税率を一覧表示します
teamleader_payment_terms_list	支払条件を一覧表示します
teamleader_withholding_tax_rates_list	源泉徴収税率を一覧表示します

組織

ツール	説明
teamleader_users_list	ユーザーを一覧表示します。必要に応じて検索語でフィルタリングできます
teamleader_users_info	ID で単一のユーザーを取得します
teamleader_users_me	現在認証されているユーザーを取得します
teamleader_teams_list	チームを一覧表示します
teamleader_departments_list	部門を一覧表示します

カスタムフィールド

ツール	説明
teamleader_custom_field_definitions_list	カスタムフィールドの定義を一覧表示
teamleader_custom_field_definitions_info	IDで単一のカスタムフィールド定義を取得

クレジットノート

ツール	説明
teamleader_credit_notes_list	クレジットノートを一覧表示。請求書または部門で絞り込み可能
teamleader_credit_notes_info	IDで単一のクレジットノートを取得

サブスクリプション

ツール	説明
teamleader_subscriptions_list	サブスクリプションを一覧表示。顧客で絞り込み可能
teamleader_subscriptions_info	IDで単一のサブスクリプションを取得
teamleader_subscriptions_create	顧客への定期請求を開始する新しいサブスクリプションを作成
teamleader_subscriptions_update	サブスクリプションのタイトルを更新
teamleader_subscriptions_deactivate	サブスクリプションを無効化（今後の請求を停止）

プロジェクト

ツール	説明
teamleader_projects_list	プロジェクトを一覧表示。検索語または顧客で絞り込み可能
teamleader_projects_info	IDで単一のプロジェクトを取得
teamleader_projects_create	顧客向けの新しいプロジェクトを作成
teamleader_milestones_list	マイルストーンを一覧表示。プロジェクトで絞り込み可能
teamleader_milestones_create	プロジェクトにマイルストーンを作成

時間追跡

ツール	説明
teamleader_time_tracking_list	時間追跡エントリーを一覧表示。ユーザーで絞り込み可能
teamleader_time_tracking_add	時間追跡エントリーを追加
teamleader_time_tracking_update	時間追跡エントリーの所要時間または説明を更新
teamleader_timer_start	タイマーを開始
teamleader_timer_stop	タイマーを停止し、時間追跡エントリーを作成

アクティビティ（電話・会議）

ツール	説明
teamleader_calls_list	電話を一覧表示。顧客で絞り込み可能
teamleader_calls_create	電話アクティビティを作成
teamleader_calls_complete	電話を完了としてマーク
teamleader_meetings_list	会議を一覧表示
teamleader_meetings_create	会議を予定
teamleader_meetings_complete	会議を完了としてマーク

チケット

ツール	説明
teamleader_tickets_list	サポートチケットを一覧表示。顧客またはステータスで絞り込み可能
teamleader_tickets_info	IDで単一のサポートチケットを取得
teamleader_tickets_create	顧客向けの新しいサポートチケットを作成
teamleader_tickets_update	チケットの件名またはステータスを更新
teamleader_tickets_add_message	チケットスレッドに返信／メッセージを追加
teamleader_ticket_status_list	利用可能なすべてのチケットステータスを一覧表示

タグ

ツール	説明
teamleader_contacts_add_tags	連絡先に1つ以上のタグを追加
teamleader_contacts_remove_tags	連絡先から1つ以上のタグを削除
teamleader_companies_add_tags	会社に1つ以上のタグを追加
teamleader_companies_remove_tags	会社から1つ以上のタグを削除

メモ

ツール	説明
teamleader_notes_list	対象（連絡先、会社、商談など）に紐づくメモを一覧表示
teamleader_notes_create	対象に紐づくメモを作成

ファイル

ツール	説明
teamleader_files_list	対象（連絡先、会社、商談など）に紐づくファイルを一覧表示
teamleader_files_download	IDでファイルの一時ダウンロードURLを取得
teamleader_files_upload	2段階のファイルアップロードを開始し、アップロードURLを返す

Webhooks

ツール	説明
teamleader_webhooks_list	登録済みの Webhook を一覧表示します
teamleader_webhooks_register	指定したイベントタイプの Webhook URL を登録します
teamleader_webhooks_unregister	指定したイベントタイプの Webhook URL の登録を解除します

---

💬 プロンプトの例

Create a quotation for deal <id> with two line items: 5 hours of consulting at €150/h and a one-time setup fee of €500.

Move the valid-until date of quotation <id> to the end of next month, then email the customer a reminder in Dutch with the signing link.

Book the draft invoice <id> into accounting and then send it to the customer.

Register a €1 200 payment against invoice <id> received today via bank transfer.

Log 2.5 hours on project <id> for user <user_id> with the note "API integration work".

Start a timer for me right now — I'm working on the BoostU onboarding project.

Open a support ticket for company <id>: subject "Login not working", priority high.

What deal phase IDs do we have in pipeline <id>? I need to move deal <id> to the "Proposal sent" phase.

List all products in the "Hosting" category and their prices.

Create a monthly subscription for company <id>: product <product_id>, quantity 1, starting next month.

Show me all open deals with their current phases and tell me which ones haven't moved in the last 30 days.

---

🐳 Docker

docker run --rm \
  -e TEAMLEADER_CLIENT_ID=your-client-id \
  -e TEAMLEADER_CLIENT_SECRET=your-client-secret \
  -e TEAMLEADER_REFRESH_TOKEN=your-refresh-token \
  -e TEAMLEADER_TOKEN_STORE=/data/teamleader-token \
  -v /var/run/teamleader:/data \
  ghcr.io/boostuagency/boostu-teamleader-mcp

---

🛠️ 開発

# Clone and install
git clone https://github.com/boostuagency/boostu-teamleader-mcp.git
cd boostu-teamleader-mcp
npm install

# Run in development mode (no build step required)
npm run dev

# Build
npm run build

# Run tests
npm test

# Type-check only
npm run typecheck

---

🏗️ アーキテクチャ

サーバーの中核は src/server.ts の createServer です。これはトランスポートに依存せず、TeamleaderClient を受け取り、有効化されたツールグループを登録して、プレーンな McpServer インスタンスを返します。エントリーポイント（src/index.ts）はこれを StdioServerTransport に接続します。ツールのロジックは src/tools/ 配下のドメインごとのモジュールにあり、それぞれが src/lib/ の共通ヘルパーを使った一貫性のある try / respond / catch / respondError パターンに従っています。OAuth2 トークンの取得とローテーションはすべて src/api/auth.ts で処理されるため、コードベースの他の部分からは透過的です。このサーバーのホスト型マルチテナント版は teamleader-mcp.boostu.be で利用できます。

---

✅ エンドポイントの検証

ほとんどの読み取りエンドポイント（*.list、*.info）は、Teamleader Focus API に対して実環境で検証済みです。いくつかの書き込みおよびアクションエンドポイント（例：subscriptions.create、projects.create、files.upload）は公式ドキュメントに基づいて実装されていますが、該当モジュールが有効な実アカウントではテストされていません。エンドポイント名が誤っている場合、呼び出しは予期しない動作をするのではなく、明確な HTTP エラーメッセージを返して失敗します。エンドポイントの全マニフェストと検証状況は docs/teamleader-endpoints.md に記載されています。

---

🤝 貢献

開発環境のセットアップ、コミット規約、新しいツールグループの追加手順については、CONTRIBUTING.md を参照してください。

---

🔒 セキュリティ

セキュリティ上の脆弱性は [email protected] に報告してください。公開の Issue は作成しないでください。開示ポリシーについては SECURITY.md を参照してください。.env ファイルや .teamleader-token をバージョン管理にコミットしないでください。どちらも .gitignore に記載されています。

---

⚖️ 免責事項

これはコミュニティによって独自に構築された統合機能です。Teamleader NV との提携、承認、スポンサー関係はありません。「Teamleader」および「Teamleader Focus」は Teamleader NV の商標であり、ここでは互換性を説明する目的でのみ使用しています。Teamleader の規約に基づく Teamleader API の利用については、ご自身の責任で行ってください。

---

📄 ライセンス

MIT License — Copyright (c) 2026 BoostU Agency。上流プロジェクトへの帰属表示については NOTICE を参照してください。