northdata-mcp

NorthData MCP サーバー

NorthData の企業データ API を Claude Desktop、Claude Code、Cursor、その他の AI アシスタントに接続します。

Model Context Protocol（MCP）は、LLM（大規模言語モデル）が NorthData のような外部サービスと通信する方法を標準化します。このサーバーは、NorthData の suggest、search、company、person、publications、reference、billing エンドポイントを MCP ツールとして公開し、誤って高コストの呼び出しを行うのを防ぐクレジットガードを組み込んでいます。ツール一覧をご覧ください。

FastMCP v3 を基盤に構築されています。トランスポートには stdio を使用します。MCP クライアントが northdata-mcp をサブプロセスとして起動します。

---

セットアップ

1. セキュリティに関する注意事項を読む

サーバーを実行する前に、セキュリティに関する考慮事項に目を通してください。NorthData では、返される企業ごとに実際の料金が発生します。また、MCP によって LLM が自律的にクレジットを消費できます。クレジットガードでリスクを軽減できますが、多層防御が重要です。

2. サーバーをインストールする

pipx install northdata-mcp

これにより、兄弟パッケージの northdata-cli が自動的にインストールされ、northdata-mcp コンソールスクリプトがグローバルに利用できるようになります。

uv を使った別の方法：

uvx northdata-mcp --help

3. NorthData API キーを取得する

https://www.northdata.com でキーを取得してください。次の手順で、MCP クライアントの設定に追加します。

クレジットガードの任意の上書き設定（MCP クライアントの設定で環境変数として指定）：

環境変数	デフォルト	用途
NORTHDATA_APPROVAL_THRESHOLD	25	これを超える search の limit には approve_high_cost=true が必要です
NORTHDATA_ABSOLUTE_MAX	100	search の limit の上限です。フラグの影響を受けません
NORTHDATA_CREDIT_LOG	~/.northdata/credits.jsonl	ローカルのクレジットログのパス

4. MCP クライアントを設定する

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json に追加します （macOS の場合）。Windows／Linux ではパスを調整してください。

{
  "mcpServers": {
    "northdata": {
      "command": "northdata-mcp",
      "env": {
        "NORTHDATA_API_KEY": "XXXX-XXXX"
      }
    }
  }
}

Claude Desktop を再起動します。ツールピッカーに NorthData のツールが表示されます。

Claude Code

claude mcp add northdata --env NORTHDATA_API_KEY=XXXX-XXXX -- northdata-mcp

Cursor

~/.cursor/mcp.json に追加します。

{
  "mcpServers": {
    "northdata": {
      "command": "northdata-mcp",
      "env": { "NORTHDATA_API_KEY": "XXXX-XXXX" }
    }
  }
}

任意の MCP クライアント（汎用）

northdata-mcp をサブプロセスとして実行し、stdio 経由で MCP を使用します。環境に NORTHDATA_API_KEY が設定されている必要があります。

---

ツール

注： このサーバーはバージョン 1.0 より前のため、バージョン間で軽微な破壊的変更が生じる可能性があります。

各ツールは、対応する northdata-cli コマンドを薄くラップしたものです。ツールには、クレジットを消費しない free、または NorthData のクレジットを消費する billed のタグが付いています。適切に動作するクライアントが UI に表示できるよう、MCP アノテーション（readOnlyHint、openWorldHint）をすべてのツールに設定しています。

無料ツール

これらのツールでは NorthData のクレジットを消費しません。

• suggest — 企業名や人物名を自動補完します。company または person でクレジットを消費する前に使える、低コストの最初のステップです。
• billing — 請求期間中の現在のリモートクレジット使用状況（numberOfRequests、periodStart、periodEnd）を表示します。
• reference_overview — API の参照データ（規格、国、法的形態、イベント）を取得します。
• reference_segment_codes — 指定した規格（デフォルトは NACE2025）のセグメントコード一覧をすべて取得します。
• local_credit_log — このサーバーがローカルで管理するクレジットログを表示します。合計、月別、エントリー別の内訳を確認できます。

課金対象のツール

これらはすべてNorthData クレジットを消費します。NorthData はリクエストごとではなく、返された企業ごとに課金します。クレジットガードは、search に対して 2 段階の上限を適用します（クレジットガードを参照）。課金対象のツールはすべて、dry_run=true を指定すると、クレジットを消費せずに URL を作成して返します。

• search — 詳細検索です。費用：最大で limit クレジット。フィルター：segment_codes、segment_standard、legal_forms、address、max_distance_km、countries、status、revenue_min/max、earnings_min/max、limit、pos、approve_high_cost。
• company — 企業の完全なプロフィール（1 クレジット）です。register（例：HRB 123456/Muenchen）、または name と省略可能な city で指定します。切り替え項目：owners、financials、representatives、extras、sheets、events。
• person — 個人検索（1 クレジット）です。生年月日と既知の役職を返します。first_name、last_name、省略可能な city を指定します。
• publications — 公告検索（1 クレジット）です。source="Hrb" を指定すると、株主リストの検索に便利です。

---

クレジットガード

NorthData は返された企業ごとに課金します。limit=100 を指定した search を 1 回呼び出すと、最大 100 クレジットがかかります。このサーバーは 2 段階の上限を適用します。

段階	デフォルト	上書き
承認しきい値 — これを超える limit には approve_high_cost=true が必要です	25	NORTHDATA_APPROVAL_THRESHOLD
絶対最大値 — approve_high_cost を無視するハード上限	100	NORTHDATA_ABSOLUTE_MAX（人間が明示的に設定します。LLM が設定することはありません）

課金対象のツール呼び出しはすべて、ローカルのクレジットログ（JSON Lines）に追記されます。local_credit_log ツールで確認できます。このログは参考情報であり、正確な情報源は引き続き billing です。

課金対象のツールで dry_run=true を指定すると、クレジットを消費する前にリクエスト URL を確認できます。

---

セキュリティ上の考慮事項

クレジットを消費するデータソースを LLM に接続すると、実際の費用とリスクが生じます。悪意のあるプロンプトや不正なプロンプトによって、エージェントがクレジットを浪費したり、構造化された企業データを信頼できないチャットに漏えいさせたり、NorthData のデータを意図しない形で他のツールと組み合わせたりするおそれがあります。

推奨事項

• クレジットガードを厳格に保ってください。 デフォルト値（承認しきい値 25、絶対最大値 100）は、エージェントが 1 回の呼び出しでクレジットを使い果たすのを防ぐためのものです。値を引き上げる場合は、意図を持って行ってください。
• 探索時は無料ツールを優先してください。 suggest、reference_*、billing は無料です。LLM は company／person／publications を使う前に、これらを呼び出してください。
• 新しい検索パラメーターや登録番号を試すときは、dry_run=true を使用してください。
• 承認前にツール呼び出しを確認してください。 多くの MCP クライアント（Claude Desktop、Cursor）は、ツール呼び出しごとに承認を求めます。この設定は有効のままにしてください。
• セッションごとに範囲を制限してください。 自由度の高い作業をエージェントに任せる場合は、メインの本番用キーではなく、試用 API キーを使ってサーバーを起動してください。
• プロンプトインジェクション。 NorthData のレスポンスには、ユーザーが生成したテキスト（企業の説明、公告）が含まれており、攻撃者がそこに指示を埋め込むおそれがあります。ツールの出力は信頼できる指示ではなく、信頼できないデータとして扱ってください。

---

開発

cd northdata-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e "../northdata-cli"   # local editable CLI
pip install -e ".[dev]"
pytest

テストでは FastMCP のインメモリトランスポートを使用します。サブプロセスもネットワークも使用しません。基盤となる NorthDataClient は、httpx.MockTransport を使用するモックファクトリー経由で注入されます。

---

リソース

• Model Context Protocol： https://modelcontextprotocol.io
• FastMCP v3 ドキュメント： https://gofastmcp.com
• NorthData API： https://github.com/northdata/api
• 関連パッケージ： northdata-cli — 同じツールをコマンドラインから利用できます

---

ライセンス

MIT。詳細は LICENSE を参照してください。