baselinker-mcp

BaseLinker API全体（注文、請求書、返品、宅配業者、CRM、倉庫、商品）を、Claude Code、Claude Desktop、Cursor などの LLM クライアントの前に置く MCP サーバーです。

• 完全対応。 文書化された API メソッド 179 件すべてを実装しており、スタブはありません。

• 明示するまで読み取り専用。 書き込みメソッド 92 件は、オプトインしない限り表示されません。書き込みを無効にすると、すべてのツールが readOnlyHint: true を報告します。

• ローカルまたはリモート。 自分のマシン上のクライアント向けの stdio、またはインターネット上の共有エンドポイント向けの OAuth 2.1（Keycloak）を備えた Streamable HTTP。

"How many orders came in yesterday that aren't paid yet?"
"Which catalog products dropped below 5 in stock this week?"
"Pull the courier label for order 1234567 and tell me the tracking number."

目次

• クイックスタート

• クライアントの接続

• ツール

• 書き込みメソッド

• 知っておくべき動作

• リモートデプロイ（HTTP + OAuth）

• 設定リファレンス

• トラブルシューティング

• 開発

Related MCP server: TextQL MCP Server

クイックスタート

要件: Node.js 20 以降、および BaseLinker パネルの アカウントとその他 → マイアカウント → API から取得した BaseLinker API トークン。

git clone https://github.com/PiotrRaszkowski/baselinker-mcp.git
cd baselinker-mcp
npm install
npm run build
cp .env.example .env     # paste your token into BASELINKER_API_TOKEN

トークンは環境変数から直接取得することもでき、.env より優先されます。.env はパッケージルートから読み込まれるため、MCP クライアントがどのディレクトリからサーバーを起動しても正しく動作します。

クライアントの接続

Claude Code

claude mcp add baselinker -e BASELINKER_API_TOKEN=your-token -- node /path/to/baselinker-mcp/dist/index.js

Claude Desktop、Cursor、または任意の mcpServers 設定

{
  "mcpServers": {
    "baselinker": {
      "command": "node",
      "args": ["/path/to/baselinker-mcp/dist/index.js"],
      "env": { "BASELINKER_API_TOKEN": "your-token" }
    }
  }
}

claude.ai から到達可能な共有エンドポイントについては、リモートデプロイ を参照してください。

ツール

179 個もの個別ツールは、モデルのコンテキストとツール選択能力を圧迫するため、メソッドは BaseLinker 自身のグループ分けに従ってグループ化されています。API カテゴリごとに 1 つのツール、合計 10 個です。各ツールは method 名と parameters オブジェクトを受け取り、各ツールの説明には受け付けるメソッドとそのパラメータ、ページネーションのヒントが列挙されています。

以下の数値は 読み取り + 書き込み です。書き込みメソッドは BASELINKER_ALLOW_WRITES=true の場合にのみ表示されます。

パラメータは送信前にメソッドごとに Zod スキーマで検証されるため、不正な呼び出しは BaseLinker のエラーコードではなく、読みやすいエラーとして返されます。未知のキーはそのまま転送されます。BaseLinker は警告なしにパラメータを追加するため、サーバーはその際に壊れません。

書き込みメソッド

デフォルトでは無効です。有効にするには:

BASELINKER_ALLOW_WRITES=true

無効の間、書き込みメソッドはどのツールの method 列挙にも含まれず、呼び出しもできません。有効にすると92 件すべてが一度に有効になります — 注文、商品、在庫、価格、請求書、出荷、返品、倉庫書類の作成、更新、削除が可能になります。一部はレコードを削除します。また、実際に費用が発生する宅配便の出荷を発送するものもあります。メソッド単位の制御はないため、信頼できるクライアントに対してのみ書き込みを有効にし、その他の用途には読み取り専用の別インスタンスを実行することを検討してください。

知っておくべき動作

レート制限。 BaseLinker は 1 分間に 100 リクエストを許可します。クライアント側のスライディングウィンドウ方式のリミッターがこれを強制し、超過した呼び出しは失敗するのではなく順番を待ちます。

ページネーション。 リスト応答には上限があります（通常、注文・請求書・返品は 100 件、カタログ商品は 1000 件）。各メソッドの説明には具体的なヒントが記載されています。たとえば getOrders は date_confirmed_from を最後に返された注文の date_confirmed に 1 秒加えた値に設定する必要があり、getInventoryProductsList は 1 から始まる page を受け取ります。

ファイルダウンロード。 getLabel、getProtocol、getCourierDocument、getInvoiceFile、getInventoryDocumentFile、getInventoryFulfillmentDeliveryLabels は、実際の MIME タイプを持つ MCP 埋め込みリソースとしてファイルを返します。追加の save_to_path パラメータ（ローカルで処理され、BaseLinker には送信されません）を渡すと、代わりにディスクにデコードして { saved_to, extension, bytes } を返します。これはサーバーが自分のマシン上で実行される stdio でのみ意味を持ち、HTTP では説明付きのエラーで拒否されます。

リモートデプロイ（HTTP + OAuth）

--transport http を使用すると、サーバーは Streamable HTTP を話し、OAuth 2.0 リソースサーバー（RFC 9728）として動作します。保護されたリソースのメタデータを公開し、認証されていない呼び出しには 401 と WWW-Authenticate チャレンジで応答し、すべてのアクセストークンを Keycloak レルムの JWKS に対する RS256 JWT として検証します。クライアントはそのメタデータからレルムを発見し、動的クライアント登録を通じて自己登録するため、どちらの側でもクライアント ID やシークレットは設定されません。

node dist/index.js --transport http --host 0.0.0.0 --port 8000 --path /mcp

HTTP トランスポートは、BASELINKER_MCP_AUTH_DISABLED=true で明示的にオプトアウトしない限り、認証レルムなしでは起動を拒否します。これは意図的です。書き込みが有効な場合、認証されていないエンドポイントはインターネットにあなたの BaseLinker アカウントを公開することになります。

deploy/ に完全なガイドがあります — Keycloak レルムのセットアップ、Traefik ラベル付きの堅牢化された Compose サービス、Caddy と nginx 用のリバースプロキシスニペット、検証コマンド、脅威モデル。短いバージョン:

docker build -t baselinker-mcp:0.2.0 .
docker run -d --name baselinker-mcp -p 8000:8000 \
  -e BASELINKER_API_TOKEN=your-token \
  -e BASELINKER_MCP_AUTH_REALM_URL=https://keycloak.example.com/realms/myrealm \
  -e BASELINKER_MCP_AUTH_BASE_URL=https://mcp.example.com \
  baselinker-mcp:0.2.0

次にクライアントをそこに向けます:

claude mcp add --transport http baselinker https://mcp.example.com/mcp

claude.ai では、設定 → コネクタ → カスタムコネクタの追加、URL https://mcp.example.com/mcp、クライアント ID とクライアントシークレットは空のままにします。

公開する前に明確にしておくべきことが 1 つあります: BaseLinker トークンは共有されます。レルムにログインできる人は誰でも同じ BaseLinker アカウントで操作します。その他の境界については SECURITY.md を参照してください。

設定リファレンス

すべては環境変数です。パッケージルートの .env は自動的に読み込まれます。

常時

トランスポート

CLI フラグがこれらより優先されます。

OAuth — トランスポートが http の場合に必須

リストはカンマまたはスペースで区切って指定できます。

トラブルシューティング

OAuth 固有のその他のケースは deploy/README.md にあります。

開発

npm run dev         # run from sources (tsx), stdio transport
npm run start:http  # built server, HTTP transport
npm test            # unit tests — fully offline, no live API calls
npm run check       # format check + typecheck + tests, what CI runs
npm run smoke       # manual smoke test against the live API (uses .env)
npm run inspect     # MCP Inspector against the built server

CONTRIBUTING.md は、ツールレジストリがどのように構成されているか、およびメソッドを追加する際に注意すべき点について説明しています。

ライセンス

MIT。BaseLinker とは提携しておらず、BaseLinker による推奨も受けていません。