socrata-mcp-server

---

概要

Socrata を基盤とする市、郡、州、連邦政府のオープンデータポータルにクエリを実行します。ポータルやデータセットを見つけ、列スキーマを確認し、SoQL クエリまたは大規模な結果セットに対する SQL を実行できます。

ツール

ツール	説明
socrata_list_portals	Socrata を利用する既知の政府オープンデータポータルを、ドメイン、組織名、データセットのおおよその件数とともに一覧表示します
socrata_find_datasets	Discovery API を介して、すべての Socrata ポータルからデータセットを検索するか、特定のポータルに絞り込んで検索します
socrata_get_dataset	ID で指定したデータセットの完全なメタデータと型付き列スキーマを取得します。SoQL クエリを作成する前に必要です
socrata_query_dataset	任意のデータセットに対して SoQL クエリを実行します。DataCanvas へのスピルオーバーに対応し、検索、選択、条件指定、グループ化、グループ条件、並べ替えを行えます
socrata_dataframe_describe	DataCanvas セッションに登録されたテーブル（スキーマ、行数、列名）を一覧表示します
socrata_dataframe_query	socrata_query_dataset で取り込んだ DataCanvas テーブルに対して、SELECT のみの SQL を実行します
socrata_dataframe_drop	DataCanvas キャンバス、またはその上のテーブルを削除します。SOCRATA_DATAFRAME_DROP_ENABLED=true によるオプトインが必要です

リソース

リソース	説明
socrata://datasets/{domain}/{datasetId}	安定した URI で、データセットの完全なメタデータと列スキーマを取得します。ペイロードは socrata_get_dataset と同じです
socrata://portals	既知の Socrata ポータルを、組織名とデータセットのおおよその件数とともにページ分割して一覧表示します

すべてのリソースデータはツールからも取得できます。エージェントのワークフローでは対応するツールを使用してください。リソースは URI でデータにアクセスできるクライアント向けです。

プロンプト

プロンプト	説明
explore_open_data	市民向けデータを調査するための、6段階の構造化ワークフローです。ポータルを検索 → データセットを見つける → スキーマを確認 → クエリを実行 → 集計 → 結果をまとめる

機能リファレンス

socrata_list_portals _tool

• Discovery カタログで稼働を確認済みの、有名な市・郡・州・連邦のポータル39件を厳選して掲載します
• ポータルごとのデータセット数は Discovery API からリアルタイムで取得し、約24時間キャッシュします（0 はポータルがカタログにデータセット資産を公開していないことを意味し、null は件数を一時的に取得できないことを意味します）
• ドメインまたは組織名によるクライアント側の部分一致フィルタリングに対応します。オフセットを指定したページネーションにより、1ページあたり最大200件を取得できます
• ドメイン（socrata_find_datasets に渡します）、組織名、おおよそのデータセット数を返します。件数には、ポータルが別の Socrata テナントからフェデレーションしているデータセットも含まれます（Austin、Illinois、Mesa、San Francisco はデータハブを通じて公開し、Seattle は関連する別のテナントのカタログに掲載されています）
• 上流でエラーが発生しても失敗しません。取得できない件数は null として返され、一覧は引き続き返されます

---

socrata_find_datasets _tool

• データセット名と説明を全文検索します。domain で検索範囲を指定し、categories／tags でフィルタリングし、only で資産タイプ（データセット、マップ、ファイル、カレンダー、ストーリー）を限定できます
• 関連性、ページビュー、作成日、更新日で並べ替えられます。オフセットページネーションにより、1ページあたり最大100件を取得できます
• データセット ID、名前、ドメイン、タグ、更新日時、column_names を返します。column_names は SoQL で使用する API フィールド名です（表示ラベルの CUISINE DESCRIPTION ではなく cuisine_description）。計算領域列は除外されます。クエリを作成する前に socrata_get_dataset を呼び出して、型付きスキーマを確認してください
• 結果がない場合は、適用されたフィルターを示し、検索範囲を広げる方法を提案する復旧ヒントを返します
• domain にはホスト名のみを指定します。URL 形式（https://data.cdc.gov/）はホストに変換されます。範囲を指定した検索では、別の Socrata テナントからフェデレーションされたものを含め、ポータルが公開するすべてのデータセットを検索し、ポータル独自のドメインで報告します
• 型付きエラー：Discovery API が 429 を返した場合は再試行可能な rate_limited、Discovery カタログにドメインがインデックスされていない場合は unknown_domain、ドメインがホスト名でない場合は invalid_domain

---

socrata_get_dataset _tool

• フィールド名、Socrata のデータ型、説明、行数（row_count_source の出典情報付き）、および利用可能な場合はライセンスを返します
• data_type 列で WHERE 句の構文が決まります。Number → 引用符なしのリテラル（year=2023）、Text → シングルクォートで囲んだ文字列（year='2023'）
• ノイズを減らすため、計算領域列（:@computed_region_*）を除外します。利用可能な場合は、列ごとの非 null 件数も含めます
• データセット ID はポータルごとに異なります。同じ socrata_find_datasets の結果にある domain を渡してください。URL 形式のドメインはホストに変換されます
• 型付きエラー：形式が不正な4×4 ID の場合は invalid_id、クエリ対象のドメインにそのデータセットがない場合は not_found（メッセージに ID とドメインが記載され、Discovery カタログが ID を保有するポータルを把握している場合は、復旧方法にそのポータルが記載されます）、ドメインが Socrata API を提供していない場合は unknown_domain（名前解決できない、Socrata ポータルではない、または別の場所にリダイレクトされる場合。最初の試行で失敗します）、ホスト名でない場合は invalid_domain、再試行可能な rate_limited（上流の Retry-After に従います）
• socrata_query_dataset の WHERE 句を記述する前に、必ず呼び出してください

---

socrata_query_dataset _tool

• すばやく全文検索するには search（$q）を使用します。または select／where／group／having／order を組み合わせて、分析を細かく制御できます。句では表示ラベルではなく、API フィールド名（socrata_get_dataset の field_name）で列を指定します。使用できる演算子は =、!=、>、<、LIKE、IN(...)、BETWEEN、IS NULL、starts_with()、contains()、AND、OR、NOT です。
• group／having と組み合わせて、count(*)、sum()、avg()、min()、max() による集計を行えます。
• not_tabular は、クエリ可能な行がないアセットを示します。only: "datasets" で検索してください。query_rejected は、行のみを要求するクエリは成功するものの、ゲートウェイがクエリ句を拒否したことを示します。クエリを簡素化し、条件付き集計には SoQL の case(condition, value, true, fallback) を使用してください。
• オフセットページネーションを使用し、1 回の呼び出しで最大 5000 行を取得できます。通常の行クエリで結果が切り詰められた場合は total_count が返されます（グループ化クエリまたは集計クエリでは返されません）。
• assembled_query は構文を学ぶための SoQL 文字列を返します。SODA 2.1 の行の値はすべて文字列ですが、geo／location 列はネストされたオブジェクトを返します。
• CANVAS_PROVIDER_TYPE=duckdb の場合、ページが limit まで埋まると、limit の値にかかわらず、条件に一致する行が最大 50,000 件 DataCanvas テーブルにスピルされます（canvas_id、table_name、canvas_row_count）。socrata_dataframe_describe で列を一覧表示してから、socrata_dataframe_query で SQL を実行してください。小さな limit（例：10）を指定すれば、インラインのページを大きくせずに大量の一致結果をステージングできます。
• 型付きエラー：not_tabular、query_rejected、invalid_id、not_found（ID、クエリ対象のドメイン、および判明している場合はその ID を保持するポータルを示します）、unknown_domain、invalid_domain、soql_error（不正な SoQL、未知の列、または型の不一致を示します。上流の socrataCode と、上流が名前を示す場合は問題の column を含みます。復旧のヒントはコードに応じて異なり、構文解析エラーには API フィールド名、未知の識別子には両方の修正方法、型の不一致には引用符のルールを示します）、rate_limited（再試行可能で、上流の Retry-After に従います）

---

socrata_dataframe_describe _tool

• 以前の socrata_query_dataset のスピルで取得した canvas_id が必要です。キャンバスは列挙できないため、省略するとテーブルの一覧ではなく canvas_id_required エラーになります。
• 登録済みの各テーブルについて、テーブル名、行数、DuckDB の列型を表示します（SODA の number は DOUBLE に変換されます）。
• CANVAS_PROVIDER_TYPE=duckdb が設定されている場合にのみ有効です。
• 型付きエラー：canvas_id_required、canvas_not_found（トークンの期限切れまたは不明を示します。新しいキャンバスをステージングするには、socrata_query_dataset を再実行してください）

---

socrata_dataframe_query _tool

• socrata_query_dataset によってステージングされた canvas_id のテーブルに対する、SELECT 専用の SQL です。DDL、DML、ファイル参照、ファイル読み取り関数、エンジン設定関数（current_schema、current_setting）は拒否されます。query_table ではなくテーブルを直接参照してください。query() が受け付けるのは単一の SQL 文字列リテラルのみです。current_schema という名前のステージング済み列を指定する場合は、テーブル名で修飾してください（t.current_schema）。
• スピルされた列の型は SODA のレスポンスヘッダーから判定されます。number 列（集計エイリアスを含む）は DOUBLE になるため、キャストなしで数値を比較できます（year > 2020、amount < 500）。テキスト列とタイムスタンプ列は VARCHAR のままです。時刻を比較するには CAST(date AS TIMESTAMP) を使用してください。
• 1 回の呼び出しで最大 10,000 行を取得でき、デフォルトは 1000 行です。
• 型付きエラー：canvas_disabled（CANVAS_PROVIDER_TYPE=none）、canvas_not_found、table_not_found、sql_rejected（SELECT 以外のクエリ、システムカタログへのアクセス、または拒否された関数を示します）
• そのまま使用できます。DuckDB は通常の依存関係として組み込まれており、デフォルトで有効です。CANVAS_PROVIDER_TYPE=none を指定すると無効になります。

---

socrata_dataframe_drop _ツール

• オプトイン：SOCRATA_DATAFRAME_DROP_ENABLED=true になるまでツールリストから除外されます。また、CANVAS_PROVIDER_TYPE=duckdb も必要です
• table_name を指定しない場合、キャンバス全体を削除します。削除後は、その canvas_id で socrata_dataframe_describe と socrata_dataframe_query を利用できなくなります。table_name を指定すると、そのテーブルだけを削除し、キャンバスとほかのテーブルはそのまま残します
• 削除したテーブルとその行数、およびキャンバスに残っているテーブルを報告します
• ステージング済みのコピーだけを削除します。socrata_query_dataset でデータを再度ステージングできます
• 型付きエラー：canvas_disabled（CANVAS_PROVIDER_TYPE=none）、canvas_not_found（不明、期限切れ、または削除済み）、table_not_found（キャンバスの availableTables を含みます）

---

socrata://datasets/{domain}/{datasetId} _リソース

• socrata_get_dataset と同じペイロードを返します。フィールド名、データ型、説明、行数、ライセンスが含まれます
• domain と datasetId は socrata_find_datasets から取得します。datasetId は4文字-4文字のパターン（例：kzjm-xkqj）に一致する必要があります
• 不正な形式のIDは検証エラーになります。また、そのドメインにデータセットが存在しない場合は not-found になります（Discovery カタログがIDを保持するポータルを把握している場合は、そのポータル名も示します）

---

socrata://portals _リソース

• 既知のSocrataポータル39件を厳選したカタログです。カーソルページネーションに対応しています（cursor パラメーター、1ページあたりの既定値は50件、上限は200件）
• ドメイン、組織名、おおよそのデータセット数を返します（0 = データセットアセットなし、null = 一時的に利用不可）。キャッシュ期間は約24時間です
• socrata_find_datasets に domain を渡すと、検索対象を1つのポータルに絞り込めます

---

explore_open_data _{プロンプト}

• 引数：topic は必須です。portal と geography は省略可能で、ディスカバリーを省略したり、WHERE句の範囲を指定したりできます
• ポータルの検索 → データセットの発見 → スキーマの確認 → クエリ → 集計 → 統合という6段階のワークフローを案内するユーザーメッセージを返します

機能

@cyanheads/mcp-ts-core を基盤としており、stdioおよびStreamable HTTPトランスポート、プラグイン可能な認証（none / jwt / oauth）、切り替え可能なストレージ（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1）、オプションのOpenTelemetryトレーシングを備えた構造化ログに対応しています。

Socrata固有の機能：

• Socrata SODA 2.1 APIとの完全な統合：select、where、group、having、order、search、limit、offsetに対応するSoQLクエリビルダー
• ポータルを横断したデータセット検索と、ポータルごとのデータセット数を取得するDiscovery API（39ポータルの厳選カタログ。件数は約24時間キャッシュ）
• IPごとのレート制限を緩和するアプリトークン対応（SOCRATA_APP_TOKEN）
• SOCRATA_DEFAULT_DOMAIN による既定のポータルドメインの設定
• DataCanvasによるスピルオーバー（組み込みのDuckDB）：大きなクエリ結果を分析クエリ用のSQLテーブルとして登録します

エージェントが利用しやすい出力：

• socrata_query_dataset のすべてのレスポンスに組み立て済みのSoQL文字列を含めるため、エージェントは構文を学習して調整できます
• 結果が空の場合の復旧ヒント：適用されたフィルターを示し、範囲を広げるための具体的な提案を返します
• 切り詰めの明示：行数が上限に達した場合は truncated / shown / cap フィールドを含め、ページ分割または上限の引き上げを案内します。結果がスピルオーバーされた場合は、ステージング済みのテーブル名と2つのデータフレームツールも示します
• すべてのツールで型付きエラー理由を返します（invalid_id、not_found、not_tabular、query_rejected、unknown_domain、invalid_domain、soql_error、rate_limited、canvas_id_required、canvas_not_found、table_not_found、sql_rejected、canvas_disabled）。それぞれに実行可能な復旧テキストが含まれます

はじめに

以下をMCPクライアントの設定ファイルに追加してください。

公開ホスト型インスタンス

公開インスタンスは https://socrata.caseyjhand.com/mcp で利用できます。インストールは不要です。Streamable HTTPで提供され、クライアントごとに設定形式が異なります。

Claude Codeの場合：

claude mcp add --transport http socrata-mcp-server https://socrata.caseyjhand.com/mcp

Cline（cline_mcp_settings.json）の場合：

{
  "mcpServers": {
    "socrata-mcp-server": {
      "type": "streamableHttp",
      "url": "https://socrata.caseyjhand.com/mcp"
    }
  }
}

Cursor（mcp.json）の場合：

{
  "mcpServers": {
    "socrata-mcp-server": {
      "url": "https://socrata.caseyjhand.com/mcp"
    }
  }
}

Claude Desktopでは、Settings → Connectors からリモートサーバーを追加できます。

セルフホスト／ローカル

{
  "mcpServers": {
    "socrata-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/socrata-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

または、npx を使用します（Bun は不要です）。

{
  "mcpServers": {
    "socrata-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/socrata-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

または、Docker を使用します。

{
  "mcpServers": {
    "socrata-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "ghcr.io/cyanheads/socrata-mcp-server:latest"
      ]
    }
  }
}

Streamable HTTP の場合は、トランスポートを設定してサーバーを起動します。

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

前提条件

• Bun v1.4.0 以上（または Node.js v24 以上）。
• 任意：Socrata アプリトークン — 任意のポータル（例：data.seattle.gov）で無料登録すると、より高いレート制限を利用できます（トークンごとに 10 req/s。トークンがない場合は、共有のスロットリング対象プールを使用します）。

インストール

1. リポジトリをクローンします：

git clone https://github.com/cyanheads/socrata-mcp-server.git

2. ディレクトリに移動します：

cd socrata-mcp-server

3. 依存関係をインストールします：

bun install

4. 環境を設定します：

cp .env.example .env
# edit .env and set SOCRATA_APP_TOKEN if you have one

設定

すべての設定は、src/config/server-config.ts の Zod スキーマによって起動時に検証されます。主な環境変数は次のとおりです。

変数	説明	デフォルト
SOCRATA_APP_TOKEN	Socrata アプリトークン（X-App-Token ヘッダー）。トークンがない場合、リクエストはソース IP ごとのスロットリング対象プールを共有します。	—
SOCRATA_DEFAULT_DOMAIN	ツール呼び出しで domain が省略された場合のデフォルトのポータルドメイン。	data.seattle.gov
MCP_TRANSPORT_TYPE	トランスポート：stdio または http。	stdio
MCP_HTTP_PORT	HTTP サーバーのポート。	3010
MCP_SESSION_MODE	セッション処理：stateful、stateless、または auto（スキーマのデフォルト値 auto は stateful に解決されます）。このサーバーでは stateless を明示的に設定しています。	stateless
MCP_AUTH_MODE	認証モード：none、jwt、または oauth。	none
MCP_LOG_LEVEL	ログレベル（RFC 5424）：debug、info、notice、warning、error。	info
CANVAS_PROVIDER_TYPE	大きな結果セット用の DataCanvas オーバーフロー処理。none を指定すると無効になります。DuckDB はサーバーに同梱されているため、追加のインストールは不要です。	duckdb
SOCRATA_DATAFRAME_DROP_ENABLED	socrata_dataframe_drop を有効にするには true に設定します。無効の場合、このツールはツール一覧に含まれません。	false
LOGS_DIR	ログファイルのディレクトリ（Node.js のみ）。	<project-root>/logs
STORAGE_PROVIDER_TYPE	ストレージバックエンド：in-memory、filesystem、supabase、cloudflare-kv/r2/d1。	in-memory
OTEL_ENABLED	OpenTelemetry instrumentation を有効にします。	false
LOG_TOOL_FAILURE_PAYLOADS	失敗したツール呼び出しごとに、引数と結果をログに記録します（キー名のみを編集します）。	false

オプションのオーバーライドの全一覧は .env.example を参照してください。

サーバーの実行

ローカル開発

• ビルドして実行：

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http
  

• チェックとテストを実行：

  bun run devcheck   # Lint, format, typecheck, security audit
  bun run test       # Vitest test suite
  

Docker

docker build -t socrata-mcp-server .
docker run --rm -e MCP_TRANSPORT_TYPE=http -p 3010:3010 socrata-mcp-server

Dockerfile のデフォルトでは、HTTP トランスポート、stateless セッションモードが使用され、ログは /var/log/socrata-mcp-server に出力されます。OpenTelemetry のピア依存関係はデフォルトでインストールされます。これらを省略するには、--build-arg OTEL_ENABLED=false を指定してビルドしてください。

プロジェクト構成

ディレクトリ	目的
src/index.ts	createApp() エントリーポイント — ツール、リソース、プロンプトを登録し、Socrata サービスを初期化します。
src/config	Zod を使用した、サーバー固有の環境変数の解析と検証。
src/mcp-server/tools	ツール定義（*.tool.ts）。ポータル一覧、データセット検索、スキーマ取得、SoQL クエリ、DataCanvas の SQL とクリーンアップを扱う 7 つのツール。
src/mcp-server/resources	リソース定義（*.resource.ts）。データセットのメタデータとポータルカタログのリソース。
src/mcp-server/prompts	プロンプト定義（*.prompt.ts）。市民データ調査ワークフローのプロンプト。
src/services/socrata	Socrata サービスレイヤー — SODA 2.1 API クライアント、Discovery API、クエリビルダー、型の正規化。
tests/	src/ の構成を反映したユニットテストと統合テスト。

開発ガイド

開発ガイドラインとアーキテクチャのルールについては、CLAUDE.md を参照してください。概要は次のとおりです。

• ハンドラーは例外をスローし、フレームワークが捕捉します。ツールのロジックに try/catch を記述しないでください
• リクエスト単位のログ記録には ctx.log を、テナント単位のストレージには ctx.state を使用してください
• WHERE 句を記述する前に socrata_get_dataset を呼び出してください。SoQL が参照するのは field_name であり、列の data_type によって引用符の付け方が決まります
• 外部 API 呼び出しは、未加工データの検証 → ドメイン型への正規化 → 出力スキーマの返却、の順で処理してください。欠落しているフィールドを決して捏造しないでください

コントリビューション

Issue の報告を歓迎します。提出前にチェックとテストを実行してください。

bun run devcheck
bun run test

ライセンス

Apache-2.0。詳しくは LICENSE を参照してください。