StatsMapped Public Data

statsmapped-mcp

StatsMapped の公開 API を、AI エージェント（Claude Desktop、Cursor、その他の MCP クライアント）向けのツールとして提供する MCP サーバーです。

StatsMapped は、公式の公開元（アイルランドについては CSO、PSRA、アイルランド中央銀行、DHLGH、NTPF、政府調達局、アイルランド向け EU Publications Office、英国については ONS/HM Land Registry/Nomis/DfE/DfT）から、アイルランド（郡別）と英国（地方自治体別）の公開データ（住宅、犯罪、健康、経済、社会福祉）を追跡しています。それぞれの数値には固有の注意事項が付されています。このパッケージを使うと、ウェブページを巡回して解析する代わりに、エージェントがツール呼び出しでデータを直接クエリできます。以下の各ツールは country 引数（"ireland" または "united-kingdom"、デフォルトは "ireland"）を受け取ります。両国では追跡対象のデータセットと地理的な区分が大きく異なるため、アイルランドのデフォルトが適用されると決めつけず、必要な国に応じて query_data／list_areas を呼び出してください。

これは薄型のクライアントです。StatsMapped の公開済み認証不要 HTTPS API（statsmapped.com/openapi.json に記載）を呼び出します。以下の機能に API キーは不要です。デフォルトでは stdio 経由でお使いのマシン上で実行されます（現時点での推奨方法です）。このパッケージがサポートするホスト型の streamable-http モードと、それに伴う実際のトレードオフについては、stdio を選ぶ理由をご覧ください。

インストール

PyPI では statsmapped-mcp として公開されています（公開を確認済み：https://pypi.org/project/statsmapped-mcp/）：

pip install statsmapped-mcp

設定

MCP クライアントの設定に追加してください（Claude Desktop の場合は claude_desktop_config.json、Cursor の場合は同等の mcp.json を使用します）：

{
  "mcpServers": {
    "statsmapped": {
      "command": "statsmapped-mcp"
    }
  }
}

ツール

4 つのツールです（元の 9 つから統合されています。query_data と compare はそれぞれ、よく似た単一用途のツールを複数用意するのではなく、指定する引数に応じて動作する 1 つのツールです）。すべてのツールは country 引数（"ireland" または "united-kingdom"。デフォルトは "ireland"）を受け取ります。アイルランドと英国ではデータセットと地理レベルが異なるため、アイルランドのデフォルトが適用されると決めつけず、対象の国に合わせて query_data／list_areas を呼び出してください。

• query_data(area_id=None, dataset=None, history_months=0, country="ireland") — 3 つのモードがあります。
  • area_id と dataset のどちらも指定しない場合：1 つの国について、StatsMapped が追跡するすべての統計情報と、そのキー、ラベル、公開されている地理レベルを返します。まずはこちらから始めてください。
  • area_id を指定し、dataset を省略した場合：1 つの地域（アイルランドなら "county:kerry"、英国なら "uk:lad:e09000033" など）で利用できるすべてのデータセットと、最新の数値および前年比を返します。注意事項として返されるのはラベルと重要度のみで、全文ではありません。目的は、個々のデータセットの詳細を取得する前に、どのデータセットが重要かを判断することです。
  • area_id と dataset の両方を指定した場合：1 つの地域における 1 つのデータセットの詳細をすべて返します。文章による要約、注意事項の全文、および（history_months を指定した場合）直近の履歴が含まれます。
• list_areas(level="county", country="ireland") — 1 つの境界レベルに属するすべての地理区分を返します。level のデフォルトはアイルランドの 26 郡です。英国独自の主要レベルは "county" ではなく "lad"（地方自治体地区）です。また、国ごとにほかのレベルも存在します（アイルランドでは local_authority／garda_division など）。
• compare(stat_key=None, level=None, pair_key=None, stat_key_a=None, stat_key_b=None, country="ireland") — 4 つのモードがあります。一度に指定できる引数の組み合わせは 1 つだけです（組み合わせを混在させるとエラーになります）。
  • stat_key のみを指定した場合：1 つのレベルに属するすべての地域を、該当する統計情報の最新値が高い順に並べて返します。
  • pair_key のみを指定した場合：登録済みの比較ペア 1 組の詳細をすべて返します。各軸のラベル／単位／公開元、相関統計（r、rho、leave-one-out 感度範囲）、および注意事項が含まれます。pair_key は、引数を指定しない以下のモードから取得できます。
  • stat_key_a と stat_key_b の両方を指定した場合：StatsMapped に、この 2 つの統計情報間の、登録済みで人手による審査済みの比較があるかを返します。レジストリに登録された比較のみが対象です。任意のペアの相関を新たに計算することはありません。comparable は bool ではなく文字列です。"yes" は登録済みで人手による審査済みのペア（その名前は pair_key で返されます）、"no" は 2 つの統計情報に共通する地理レベルがないこと、"unknown" は登録されていないものの、可能性が否定されていないことを意味します。この場合は「おそらく可能」ではなく、「人に確認する」と扱ってください。ほとんどのペアでは "unknown" が通常の結果です。値を明示的に比較してください（result["comparable"] == "yes"）。真偽値として評価すると、3 つすべてが true になります。reasons（リスト）には、常に回答の理由が記載されます。
  • 上記の引数をどれも指定しない場合：1 つの国における、データセットをまたぐ登録済み比較ペアをすべて返します（例：「住宅の中央値の販売価格と、住民 1,000 人あたりの新築住宅完成数」）。対象は人手で厳選された少数のペアであり、任意のペアを比較するエンジンではありません。
• explain_metric(stat_key, country="ireland") — 1 つの統計情報の定義、測定方法、恒常的な注意事項を返します。現在の数値は返しません。指標の意味や測定方法について尋ねられた場合に使用してください。ある地域の値について尋ねられた場合には使用しないでください。

デフォルトでホステッドサーバーではなく stdio を使う理由

StatsMapped は単一の無料枠インスタンスで稼働しています。そこにホストされたリモート MCP エンドポイントを設置すると、エージェント自身が複数地域を対象にクエリを行うパターン（ループ内で同じツールを地域ごとに1回呼び出す）によって、大規模な地理的ファンアウトの際にそのインスタンスでタイムアウトをすでに引き起こしているのとまったく同じ負荷パターンが再現されます。stdio 経由で実行すれば、すべての呼び出しは、このパッケージのツールが直接呼び出すのと同じ公開 HTTPS API に、ユーザー自身のネットワーク接続を通じて行われ、共有のボトルネックは発生しません。HTTP 呼び出しは各ユーザー自身のマシンから行われるため、N 人のユーザーのトラフィックは1つの送信元 IP に集約されず、N 個の送信元 IP に自然に分散されます。

server.py は、そうしたトレードオフを受け入れるデプロイ向けに、実際のホステッド streamable-http モード（MCP_TRANSPORT=streamable-http）もサポートしています。StatsMapped の公開 API 自体は送信元 IP ごとにレート制限（600リクエスト/時間）されていますが、ホストされた MCP エンドポイントは、すべてのリモートユーザーの呼び出しを1つの共有送信元 IP からプロキシします。そのため、ホストされたエンドポイントを利用するすべてのリモートユーザーは、それぞれ個別の枠を得るのではなく、同じ枠を共有することになります。StatsMapped がホストするエンドポイントは https://mcp.statsmapped.com/mcp（Streamable HTTP）で稼働しており、正常に応答することを確認済みです。Streamable HTTP に直接対応するクライアントであれば、別途インストールする必要はありません。ホスト名のみ（パスなし）の https://mcp.statsmapped.com にアクセスした場合は、便宜上、同じエンドポイントにリダイレクトされます。

開発

cd mcp-server
pip install -e .
python tests/test_client.py

テストスイートは実際の稼働中 API に対して実行されます（デフォルトは https://statsmapped.com、STATSMAPPED_MCP_BASE_URL が設定されている場合はその URL）。読み取り専用の GET リクエストのみを使用し、ここでデータを書き込むことはなく、キーも必要ありません。

ライセンス

このパッケージは MIT ライセンスです。基盤となるデータには、各発行元独自のライセンスが適用されます。エージェント経由でクエリする以外の目的で数値を再利用する前に、アイルランドの発行元とライセンスの詳細を statsmapped.com/ireland/sources で確認してください（英国版に相当するページはまだありません。現時点では、各英国ツールの応答に含まれる caveats／sources フィールドを確認してください）。