Simpro MCP server

非公式。 これは独立したサードパーティプロジェクトです。Simpro とは提携しておらず、 Simpro から承認もサポートも受けていません。

AI エージェントがあなたの Simpro アカウントを操作できるようにします。Simpro からほぼすべての情報を検索し、通常なら複数の画面をクリックして回ることになる数値をまとめて取得できます。あなたが平易な英語で質問すると、エージェントが Simpro での検索や変更を行います。

Simpro API のすべての部分に到達できるため、特定の用途に特化したツールが用意されていない場合でも、エージェントはそれにアクセスできます。

⚠️ このツールは読み取りだけでなく、書き込みや削除もできます。 Simpro API 全体にアクセスでき、レコードを更新・削除するエンドポイントも含まれます。このツールを操作する AI エージェントは、誤操作や誤った指示に従った結果、稼働中の Simpro アカウント内の見積もり、ジョブ、顧客、カタログ項目などを、元に戻せない形で一括変更・破壊する可能性があります。このツールは、あなたが渡したキーまたはログインが持つ権限で動作します。信頼できないエージェントには渡さないでください。本番環境に対して無人で実行させないでください。実際に必要な範囲に限定した Simpro ログイン/キーを与えてください。 読み取り専用の安全性が必要な場合は、読み取り専用権限を持つ Simpro ユーザーを作成し、そのユーザーとして認証してください。

これは、私たち自身の MCP Gateway の背後にある社内ツールから開発されました。コミュニティ向けに少し機能を追加していますが、mcbp と OAuth Broker モードは社内では使用していません。

本ソフトウェアは、明示または黙示を問わず、**いかなる保証もなく「現状のまま」**提供されます。 自己責任で使用してください。著者らは、本ソフトウェアの使用によって生じた Simpro データの損失、損害、変更について、一切の責任を負いません。

Prerequisites

• Claude Desktop へのインストール（オプション 1): Claude Desktop と Simpro OAuth アプリだけが必要です。.mcpb バンドルにはランタイムが同梱されています。

• ソースから実行する場合やセルフホストする場合（オプション 2 および 3): Node.js 24 以降と npm が必要です。

• アクセス可能な Simpro ビルドと、その中に作成した OAuth アプリ（またはレガシー API キー）が必要です。各モードのセクションに、必要なものが正確に記載されています。

Related MCP server: ServiceTitan MCP Server

Contents

• Claude Desktop にインストール（簡単な方法）

  • Simpro で必要なもの

  • インストール

  • ログイン（OAuth フロー）

  • 他の認証方法

  • ソースからローカルで実行する

• OAuth Broker モード（AI エージェントコネクタ用）

• HTTP Proxy モード（共有/ホスト型セットアップ用）

• どのモードを選べばいいか？

• クライアントの接続（設定スニペット）

• ブローカーが Simpro のサインインをどう拡張するか

• 自分でビルドする

1. Claude Desktop にインストール（簡単な方法）

コマンドラインもセットアップファイルも必要ありません。Claude Desktop の拡張機能設定から .mcpb バンドルをインストールし、短いフォームに入力して、ブラウザで Simpro に一度ログインするだけです。以降、エージェントはサインインしたままになり、あとはチャットするだけです。

Simpro で必要なもの

Simpro OAuth アプリで認証します。このアプリは Simpro 自身のログイン画面からサインインさせる方法で、推奨される方法です。Simpro の Setup → Integrations → API → New API Key で作成します（OAuth / "Authorization Code" アプリケーションを選択）。その後、以下を控えておきます。

重要なステップが 1 つあります: Simpro OAuth アプリで、Redirect URI を http://localhost:8237/callback に設定してください。これはログイン後に Simpro があなたを戻す場所です。正確に一致する必要があります。もしマシンでポート 8237 がすでに使用中の場合は、別のポートを選び、インストール画面の対応する Auth redirect port に設定してください。ただし、登録済みの Redirect URI も同じポートを使う必要があります。

インストール

1. 最新の simpro-mcp-server.mcpb ファイルを Releases ページ からダウンロードします。

2. Claude Desktop で Settings → Extensions を開き、Advanced settings をクリックしてから Install extension をクリックします（その前に、開発者/拡張機能インストールを有効にする必要があるかもしれません）。ダウンロードした simpro-mcp-server.mcpb ファイルを選択します。インストール画面が表示されます。

3. 次の項目を入力します:

   • Build URL と Company ID

   • Authentication mode - 既定の authorization_code（ブラウザログイン）のままにします。

   • Simpro OAuth アプリの Client ID と Client secret

   • 別のポートを登録していない限り、Auth redirect port は 8237 のままにします。

4. インストールをクリックします。

ログイン（OAuth フロー）

エージェントが初めてツールを使用するとき、ブラウザのタブが Simpro のログイン画面で開きます。ログインしてアクセスを承認してください。タブに "✓ Authorised" と表示されたら、タブを閉じてチャットに戻ります。

ログインはその一度だけです。ツールはリフレッシュトークンをキャッシュするため、再起動後もサインイン状態が維持され、トークンが失効または期限切れになるまで再度プロンプトが表示されることはありません。万一そのような状態になった場合も、再びログインタブが開くだけです。

これで完了です。チャットを開始して、「Acme のオープンな見積もりを見せて」 や 「ジョブ 4521 には何が含まれていますか？」 のように質問してみてください。

Page size はインストール画面のオプション設定です。50 のままにしてください。これは一度に返される行数を制限するだけで、大きなリストが 1 つの回答を圧倒しないようにするためのものです。エージェントはいつでもさらに要求できます。

他の認証方法

インストール画面の Authentication mode フィールドには、次の 3 つの選択肢があります。

認証情報を安全に保つ

クライアントシークレット、リフレッシュトークン、および API キーは Claude Desktop によって保存され、自分の Simpro ビルドと通信するためだけに使用されます。これらを入手した人は、あなたが付与したのと同じアクセス権で Simpro を操作できるため、.mcpb インストールやこれらの値を、そのアクセス権を持つべきでない人と共有しないでください。認証情報が漏えいした場合は、Simpro で OAuth アプリまたはキーを失効させ、新しいものを作成してください。

ソースからローカルで実行する

開発者向け、または .mcpb バンドルではなく Git チェックアウトから実行する人向けです。 上記の拡張機能をインストールした場合は、ここはスキップして構いません。

1. .env.example を .env にコピーし、SIMPRO_BASE_URL と SIMPRO_COMPANY_ID を設定します。さらに、SIMPRO_CLIENT_ID + SIMPRO_CLIENT_SECRET（ブラウザログインまたはマシンログイン用）または SIMPRO_API_KEY（レガシーキー）のどちらかを設定します。

2. 認証モードは設定内容から自動的に決定されます。クライアント ID とシークレットの両方が存在する場合は client_credentials、それ以外の場合は api_key になります。ブラウザログインを強制するには、SIMPRO_AUTH_MODE=authorization_code を設定します。

3. npm install && npm run build && npm start - これは stdio 経由で実行され、インストール済みの拡張機能と同じです。

ブラウザログイン（authorization_code）の場合、あらかじめ npm run login で一度サインインできます。Simpro のログインタブが開き、リフレッシュトークンが .simpro-tokens.json にキャッシュされます。この手順をスキップした場合、サーバーは初めてツールが使用されたときに同じログインを実行します。スクリプトの完全な一覧は 自分でビルドする を参照してください。

2. OAuth Broker モード（AI エージェントコネクタ用）

Simpro を AI エージェントに正規のコネクタとして接続するためのモードです。各ユーザーが通常の Simpro ログイン画面から自分自身で Simpro にサインインします。共有キーも、ユーザーごとのセットアップファイルもありません。サーバーで実行するほとんどの人にとって、このモードが適しています。

同梱の Docker セットアップが既定で使用するモードです。 これがより安全な既定です。サーバーは上流から渡された認証情報を信頼するのではなく、ユーザー自身を認証します。TLS を終端し、PUBLIC_URL をこのサーバーにルーティングするリバースプロキシの背後に置く必要があります。ただし、インバウンドヘッダーを信頼するかどうかを決定するのは、コンテナではありません。

Simpro 独自のサインインは OAuth 2.0 ベースの設計で、最新のエージェントコネクタは直接接続できません。このサーバーはその中間に立ち、コネクタが要求する OAuth 2.1 標準に引き上げます。Simpro に欠けているセキュリティ手順を追加しつつ、実際の Simpro ログインに引き継ぎます。ユーザーから見れば、「接続をクリックして Simpro にログイン」するだけです。追加される正確な手順は、下の ブローカーが Simpro のサインインをどう拡張するか に記載されています。

サーバーは Simpro の前に立ち、サインインハンドシェイクを実行します。ユーザーはエージェントにコネクタを追加し、Simpro にログインするよう送られ、以降、エージェントはそのユーザーとして Simpro 内で動作します。ユーザーの Simpro アクセス権は、エージェントが保持するトークンの中に封じ込められています。サーバーはログインのデータベースを保持しません。

このモードでは、公開 Web アドレスと Simpro OAuth アプリ（Simpro の Setup → Integrations で作成）が必要です。その OAuth アプリで、Redirect URL を公開アドレスの後に /callback を付けたもの、たとえば https://simpro.yourcompany.com/callback に設定します。

設定

上記の SIMPRO_BASE_URL（および必要に応じて SIMPRO_COMPANY_ID）に加えて、次の環境変数を設定します。

このモードでは SIMPRO_API_KEY を設定しないでください - サーバーが起動を拒否します。

3. HTTPプロキシモード（共有/ホステッド環境向け）

サインインをすでに処理する何らかのシステムの背後にあるサーバー上で実行するチーム向け （例: Cowork や Copilot のセットアップ）。このモードでは、サーバーは独自の Simpro キーを保持しません - 各リクエストは、ユーザーをサインインさせるものが添付した、それぞれのログイン情報を持ち込みます。サーバーはそれを Simpro にそのまま渡すだけです。

⚠️ インターネットに直接公開することを想定していません。 このモードは ゲートウェイまたはリバースプロキシ（MCPゲートウェイ、Context Forge、nginx/Traefik など）の背後で実行する必要があります。ゲートウェイが TLS を終端し、ユーザーを認証します。このモード自体は認証を行わず、直接公開するための堅牢化もされていません - インターネットに直接公開しないでください。コンテナは意図的にホスト上にはデフォルトで公開されておらず、ゲートウェイがプライベートネットワーク経由で到達します。

このモードを使用するには、SIMPRO_TRANSPORT=proxy を設定します（付属の Docker セットアップはデフォルトでより安全な上記のブローカーモードを使用します）。Portainer や Context Forge でデプロイする場合は、スタック構成について docs/deploy.md を参照してください。

ここでは API キーは設定しません。実際、キーが存在するとサーバーは起動を拒否します。このモードでは、アクセスを許可する唯一の情報はユーザーごとのログインだからです。

重要 - このモードは独自のチェックを行いません。 リクエストとともに届いた Authorization ヘッダーは、そのまま変更されずに Simpro に転送されます。サーバーは、資格情報が有効か、期限切れでないか、リクエストが許可されたユーザーからのものであるかを検証しません - 資格情報が機能するかどうかを決定するのは Simpro だけです。これは設計上の意図です。このモードは、前面にあるレイヤー（ゲートウェイまたはサインインシステム）がユーザーをすでに認証し、信頼できるヘッダーを添付していることを前提としています。このモードはそのようなレイヤーの背後でのみ実行してください。 直接公開すると、到達できる人は誰でも自分のヘッダーをそのまま Simpro に渡すことができます。

設定

これらは環境変数（.env ファイルまたはコンテナプラットフォーム）として設定します。

このモードでは SIMPRO_API_KEY を設定しないでください - サーバーが起動を拒否します。

一度に返されるデータ量も調整できます:

4. どのモードを選ぶべきか?

5. クライアントの接続（設定スニペット）

Claude Desktop の .mcpb インストール（オプション1）は独自の設定を書き込みます - その場合は JSON に触れる必要はありません。ここでのスニペットは、ソースチェックアウトから実行する場合、またはクライアントをホストされているブローカー/プロキシに向ける場合のためのものです。

Claude Desktop - ソースからの stdio

claude_desktop_config.json を編集します（設定 → 開発者 → 設定を編集）。command を node に、args をビルド済みの dist/index.js に設定し、Simpro の設定を env として渡します:

{
  "mcpServers": {
    "simpro": {
      "command": "node",
      "args": ["/absolute/path/to/simpro-mcp/dist/index.js"],
      "env": {
        "SIMPRO_BASE_URL": "https://yourbuild.simprosuite.com",
        "SIMPRO_COMPANY_ID": "0",
        "SIMPRO_AUTH_MODE": "authorization_code",
        "SIMPRO_CLIENT_ID": "your-oauth-client-id",
        "SIMPRO_CLIENT_SECRET": "your-oauth-client-secret"
      }
    }
  }
}

最初にビルドします（npm install && npm run build）。Windows では、エスケープされたバックスラッシュ付きの完全パスを使用します（"C:\\path\\to\\simpro-mcp\\dist\\index.js"）。レガシーキーを使用する場合は、クライアントID/シークレットを削除して、代わりに "SIMPRO_API_KEY" を設定します（stdio のみ）。

Claude Code - claude mcp add

同じ stdio サーバーを CLI から登録します（チェックアウトから実行するか、絶対パスを使用します）:

claude mcp add simpro \
  --env SIMPRO_BASE_URL=https://yourbuild.simprosuite.com \
  --env SIMPRO_COMPANY_ID=0 \
  --env SIMPRO_AUTH_MODE=authorization_code \
  --env SIMPRO_CLIENT_ID=your-oauth-client-id \
  --env SIMPRO_CLIENT_SECRET=your-oauth-client-secret \
  -- node ./dist/index.js

ホストされているブローカーへのクライアント接続（オプション2）

ブローカーが公開アドレスの背後で実行されたら、それをリモートコネクタとして追加します - ローカルコマンドや env はありません。クライアントのコネクタ/"カスタムコネクタの追加" UI を使用して、MCP URL を指定します:

https://simpro.yourcompany.com/mcp

クライアントは Simpro にログインするよう誘導されます。他に設定するものはありません。（オプション3 の HTTPプロキシも同じ方法で到達できますが、ゲートウェイがベアラーを添付することを想定しています - ベアコネクタとしては追加されません。）

6. ブローカーが Simpro のサインインをアップグレードする仕組み

このセクションは技術に興味がある方、またはコネクタのセキュリティをレビューする方向けです。上記の3つのモードを使用するためにこれを理解する必要はありません。

最新のエージェントコネクタは、OAuth 2.1 の基準を満たす認可サーバーにのみ接続します。Simpro の OAuth は PKCE に対応しておらず、それらのコネクタが使用するクライアント ID スキームもサポートしていません。Simpro に変更を求めるのではなく、ブローカーはそれ自体が準拠した OAuth 2.1 認可サーバーとして Simpro の前面に立ち、背後で静かに Simpro に中継します。具体的には、以下を追加します:

• PKCE（S256）、当方が強制。 接続するクライアントは /authorize でコードチャレンジを送信し、/token でそれを証明しなければなりません。不一致は拒否されます。Simpro 自体は PKCE を行わないため、実際に強制するのはブローカーです。これにより、素の 2.0 が残す認可コード盗用の隙間を塞ぎます。

• モダンなクライアント ID — クライアントに共有シークレットを組み込まない。 接続するクライアントは、標準的な 2 つの方法のいずれかでブローカーに自身が誰であるかを伝えます。ブローカーは、そのクライアントが使うほうを受け付けます。

  • CIMD（client-ID-metadata-document）：client_id は、ブローカーがリクエストごとにフェッチして検証する URL です。自己参照的であり、使用中の正確なリダイレクトアドレスを列挙している必要があります。事前登録は一切ありません。フェッチは SSRF 対策ガードの背後で実行されるため、その URL を使ってサーバーの内部ネットワークを探ることはできません。

  • DCR（動的クライアント登録、RFC 7591）：クライアントは POST /register で自分の client_id をあらかじめ発行できます。ブローカーはこのエンドポイントを自身のメタデータで公開します。登録はオープン（認証なし）なので、レートとサイズに上限があり、上限に達すると最も古いエントリから追い出されます。登録済みクライアントは永続化されるため、再起動後も存続します。クライアントは、公開（シークレットなし）または機密（ブローカーがシークレットを発行し、トークンステップでそれを要求する）として登録できます。

  いずれにしても、下流のクライアントの ID が Simpro に届くことはありません。ブローカーは固定された 1 つの Simpro 登録を保持し、その登録の下で中継します。

• リダイレクトの完全一致。 クライアントが送り返されるアドレスは、登録済みのアドレスと 1 文字単位で一致しなければなりません。「前方一致」だけでは不十分です。

• 短命でオーディエンスに紐づくトークン。 クライアントが受け取るトークンはブローカーが発行するもので、有効期限が刻印され、オーディエンスとしてこの特定のサーバーに紐づけられています。実際の Simpro トークンは、その内部に暗号化（シール）されて格納されています。ブローカーはトークンデータベースを保持しません。すべてのトークンは自己完結型であり、発行されるリフレッシュトークンには最大 30 日の有効期限があるため、漏洩したトークンを無期限にリプレイすることはできません。唯一の例外：Simpro はリフレッシュトークンを使用のたびにローテーションする（リフレッシュのたびに古いトークンを無効化する）ため、ブローカーはログインごとに現在のアップストリームリフレッシュトークンをメモリ内にのみ数分間保持します。これにより、リフレッシュ応答を落としてしまったクライアントは再ログインを強制されません。ディスクに書き込まれることはありません。次のリフレッシュが成功すると（クライアントが現在のトークンを保持していることが確認される）、保持していたトークンは破棄されます。再起動または数分間のアイドルでもクリアされます。

正味の効果：エージェントはクリーンでモダンな OAuth 2.1 プロバイダーのように見えるものと通信し、ユーザーは引き続き本物の Simpro 画面でログインし、Simpro のフローの脆弱な部分は中間で補強されます。ハンドシェイクに要する数秒間だけ、やり取り全体がメモリ上でのみ関連付けられます。そのため、このモードは単一インスタンスとして実行する必要があります。ロードバランサーの後ろには置かないでください。

自分でビルドする

単に使用するだけでなく、コードを扱う場合：

npm install
npm run build        # compile
npm test             # run the unit tests
npm run login        # one-time browser sign-in (authorization_code); caches the refresh token
npm run build:mcpb   # produce the simpro-mcp-server.mcpb install file
npm start            # run it locally

npm run login はコンパイル済みの dist/login.js を実行するため、先にビルドしてください。SIMPRO_CLIENT_ID と SIMPRO_CLIENT_SECRET の設定が必要です（上記のソースからローカルで実行を参照）。

純粋で決定論的な部分（検索ランキング、出力フォーマット、明細項目パス、認証の暗号／ストアヘルパー）をカバーする単体テストスイート（npm test）があります。リンターはなく、ネットワークをモックするものもないため、変更を完全に確認するには、やはりビルドして実際の Simpro アカウントに対して試す必要があります。アーキテクチャに関するメモと、知っておくべき Simpro API の癖は CLAUDE.md に記載されています。