makeleaps-mcp

MakeLeapsの取引先、見積書、請求書をLLMから操作するための、非公式・ローカル実行専用MCPサーバーです。

HubSpotなど他サービスとの接続処理は含みません。LLMクライアントがHubSpot ConnectorとこのMCPサーバーを同時に利用し、必要な情報をツール間で受け渡す構成を想定しています。

IMPORTANT

このプロジェクトはMakeLeaps株式会社による公式製品ではありません。MakeLeaps APIを利用した実装について、MakeLeapsは技術サポートを提供していません。

特徴

stdioによるローカル実行のみ
ホステッドサービス、リモートHTTP、テレメトリーなし
MakeLeapsの認証情報と請求データを開発者側へ送信しない
金額を浮動小数点数ではなくDecimalとして検証
MakeLeapsのテンプレートに応じた税区分の検証
ローカルSQLiteを用いた書き込み操作の二重実行防止
書類の送付機能は提供しない

利用者向け

提供ツール

ツール	内容
`search_clients`	取引先の一覧取得・検索
`get_client`	取引先とデフォルト連絡先の取得
`create_organization_client`	法人取引先の作成
`list_document_templates`	見積書・請求書テンプレートの取得
`search_documents`	見積書・請求書の検索
`get_document`	書類詳細の取得
`create_quote`	見積書の作成
`create_invoice`	請求書の作成

create_quoteとcreate_invoiceは書類をMakeLeapsへ保存しますが、取引先への送付は行いません。 HubSpotのDeal名など、書類の案件名はproject_nameで指定できます。

create_organization_clientでは法人名に加えて、法人のメールアドレス・電話番号・FAX番号・住所・適格請求書発行事業者登録番号と、任意の担当者を登録できます。住所を指定する場合は、MakeLeaps APIの仕様に従ってformatと2文字の国コードcountry_nameが必須です。

書類には取引先向けの備考messageとは別に、MakeLeaps内だけで使用する社内メモnoteと発注番号purchase_order_idsを設定できます。create_invoiceでは請求対象期間も指定できます。

必要環境

Python 3.12以上
uv
MakeLeapsのAPI Client ID、Client Secret、Partner MID

MakeLeapsの管理画面からAPIキーを発行してください。APIは本番データへ接続され、サンドボックス環境は提供されていません。

セットアップ

git clone https://github.com/Swandive-Inc/makeleaps-mcp.git
cd makeleaps-mcp
uv sync --frozen

次の環境変数をMCPクライアントから渡します。

環境変数	必須	内容
`MAKELEAPS_CLIENT_ID`	はい	MakeLeaps API Client ID
`MAKELEAPS_CLIENT_SECRET`	はい	MakeLeaps API Client Secret
`MAKELEAPS_PARTNER_MID`	はい	MakeLeaps Partner MID
`MAKELEAPS_STATE_PATH`	いいえ	冪等性管理用SQLiteファイルの保存先

MAKELEAPS_STATE_PATHを省略した場合は、OS標準のユーザーデータディレクトリへ保存します。認証トークンや書類本文はSQLiteへ保存しません。

MCPクライアントの設定例です。パスと認証情報を利用環境に合わせて変更してください。

{
  "mcpServers": {
    "makeleaps": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\path\\to\\makeleaps-mcp",
        "run",
        "makeleaps-mcp"
      ],
      "env": {
        "MAKELEAPS_CLIENT_ID": "your-client-id",
        "MAKELEAPS_CLIENT_SECRET": "your-client-secret",
        "MAKELEAPS_PARTNER_MID": "your-partner-mid"
      }
    }
  }
}

秘密情報を.envやMCPクライアントの設定ファイルへ保存する場合は、ファイルのアクセス権とバックアップ先を確認してください。秘密情報をGitへコミットしないでください。

LLMへの依頼例

HubSpotのDeal 12345を取得し、会社と担当者をMakeLeapsで検索してください。
見積内容を提示して私の確認を取ったあと、MakeLeapsへ見積書を作成してください。
送付はしないでください。

利用上の注意

HubSpotのIDをexternal_idへ保存する場合は、既存運用で同フィールドを使っていないか確認してください。すでに別システムとの対応付けに利用している場合は上書きしないでください。
APIへの送信後に通信が切れた場合は、MakeLeaps上で作成結果を確認してください。

開発者向け

二重作成の防止

書き込みツールはoperation_keyを必須引数とし、呼び出し元と対象を識別できる安定した値を受け取ります。

hubspot:deal:12345:quote:v1

同じキーと同じ入力を再実行すると、MakeLeaps APIを再度呼ばず、ローカルSQLiteに保存した結果を返します。同じキーを異なる入力で再利用した場合はエラーになります。

APIへの送信後に通信が切れた場合は、結果が確定できないため同じ操作を自動再実行しません。通信結果が不明なまま書類を二重作成することを防ぐためです。

開発

uv sync --frozen
uv run ruff format --check .
uv run ruff check .
uv run pytest

テストはMakeLeaps APIをモックし、本番アカウントへ接続しません。

セキュリティ

MCPサーバーはstdioのみで動作し、待受ポートを開きません。
APIアクセストークンはメモリ内でのみ保持し、期限切れ前に更新します。
顧客情報、書類内容、認証情報をログへ出力しません。
書類送付や削除のツールは実装していません。

参考資料

ライセンス

MIT License