census-mcp-server

---

概要

米国国勢調査局の人口統計、経済、住宅に関するデータを扱います。データセットや変数を探したり、地名や住所から FIPS コードを特定したり、任意の地理的範囲にわたる推計値を照会または順位付けしたりできます。

ツール

ツール	説明
census_list_datasets	利用可能な Census Bureau データセット（ACS5 および ACS1 のプロファイル、主題別、比較テーブル、ACS 補足推計および選択された人口プロファイル、人口推計、10 年ごとの国勢調査、郡別事業所統計、経済センサス、非雇用者統計）を、ビンテージ年とデータセットコードとともに閲覧します。
census_list_geographies	データセットと年でサポートされる地域レベルを、親地域の要件と FIPS の例とともに一覧表示します。
census_search_variables	変数ラベルと概念グループをキーワード検索するか、変数コードまたはテーブルコードで検索します。ACS では、推計値と誤差範囲のコードをあわせて返します。
census_get_variable	1 つ以上の変数コードについて、ラベル、概念、述語タイプ、母集団、誤差範囲の対応変数などの完全なメタデータを取得します。データツールが受け付ける注釈列とフラグ列も含まれます。
census_list_predicate_values	データセットの辞書またはライブのワイルドカード列挙から、フィルター対象のディメンションが受け付けるコード（EMPSZES、LFO、POPGROUP、NAICS2017…）を一覧表示します。
census_resolve_geography	TIGERweb と Census Geocoder を介して、地名（例：「King County, WA」）、ZIP コード、または住所を Census FIPS 識別子に変換します。
census_query_data	特定の地域における変数について、Census データセットにクエリを実行します。誤差範囲を含む推計値、Census のセンチネル値、および公開済みの意味に変換された非公開事業所の値を返します。また、事業所データセットの述語フィルタリングにも対応します。
census_compare_geographies	州内のすべての郡、全国のすべての州、または指定した地域セットを対象に、複数の地域間で変数を順位付けして比較します。同じ述語フィルタリングに対応した、ソート済みのテーブルを出力します。

---

機能リファレンス

census_list_datasets _ツール

• データセットコード、名称、説明、および利用可能なビンテージ年を返します。キーワードによる絞り込みは任意です。ACS5 および ACS1（データプロファイル、主題別テーブル、比較プロファイル、acs/acs1/spp）、acs/acsse、人口推計、2020 年の 10 年ごとの国勢調査ファイル（選挙区再編成（P.L. 94-171）、dec/dhc、dec/dp、dec/sdhc、dec/ddhca、dec/ddhcb）、cbp、ecnbasic、および nonemp を対象とします。
• 各説明には、データセットで必要なフィルター述語と、公開されている地域レベルが記載されています。
• データセットコード（例：acs/acs5）は、他のツールに渡す値です。大文字と小文字は区別されません。また、2 つの部分で構成されるコードは最後の部分だけでも使用できます（acs5、pl）。acs/acs5/profile などの 3 つの部分で構成されるコードは、完全な形で指定する必要があります。
• available_years はすべての利用可能年を示します。それ以外の年を指定すると year_not_available が発生し、利用可能な年が示されます。

---

census_list_geographies _ツール

• 地域レベルと親階層ごとに 1 行を返します。内容は geography_level、親地域が必須かどうか、required_parent_levels、FIPS の例です。totalLevels は各レベルを 1 回ずつ数えます。
• geography_level の値は census_query_data および census_compare_geographies にそのまま渡す値です。year のデフォルトは最新のビンテージ年です。
• dataset_not_found または year_not_available（提供される年を明記）が発生します。

---

census_search_variables _ツール

• ラベルと概念を対象に単語単位で検索します。クエリ内のすべての単語が一致しない場合は、最も近い候補が通知とともに返されます。大文字・小文字を問わず変数コードまたはテーブルコードを指定すると、最初にその変数、またはコード順のテーブル全体が返されます（B19013 の場合は、まず B19013_001E、次に B19013_001M が返されます）。
• データセットで公開されていないコードを指定すると、そのコードを含む兄弟データセットを示す通知が返されます（acs/acs5 の S1701 は acs/acs5/subject を示します）。B19013_001EA などの属性列には census_get_variable を使用してください。
• ACS データセットでは、推定値（E 接尾辞）と誤差範囲（M 接尾辞）のコードがセットで返されます。比較プロファイルとその他のファミリーでは、誤差範囲は公開されません。また、キーワード（naics）またはコード（cbp の NAICS2017）で述語コードも検索できます。
• limit は 1～100 の整数です（既定値は 20）。範囲外の値は上限・下限に丸めず、拒否されます。totalMatches は上限適用前の一致件数です。variables.json はデータセットと年ごとにキャッシュされます（既定の TTL は 24 時間）。

---

census_get_variable _ツール

• 1 つ以上の変数コード（大文字・小文字は区別されません）を受け取り、指定された順にラベル、概念、述語の型、テーブルの母集団を返します。groups.json を取得できない場合、変数は母集団情報なしで返され、再試行するよう通知されます。
• B19013_001EA や EMP_F などの注釈列とフラグ列を解決します。attribute_of は各列が属する列を示し、attribute_type はその種類（ANNOTATION、FLAG、MARGIN_OF_ERROR）を示します。ACS データセットでは、兄弟列への参照として estimate_code／moe_code も返されます。
• 述語ディメンションコード（NAICS2017、SEX）がデータセットに存在することを確認します。それらの値は census_list_predicate_values で一覧表示できます。dataset の既定値は acs/acs5、year の既定値は最新のデータ年です。
• コードが定義されていない場合は variable_not_found が返され、見つかった場合はそのコードを公開している兄弟データセットが示されます（acs/acs5 の DP03_0062E は acs/acs5/profile を示します）。

---

census_list_predicate_values _ツール

• フィルターディメンションで使用できるコードを一覧表示します。データセットの辞書に一覧がある場合はそこから読み込み、ない場合はその都度列挙します。NAICS* と POPGROUP は一覧が長く（数千件のコード）、query で絞り込めます。EMPSZES、LFO、RCPSZES、TAXSTAT、TYPOP はその都度取得する値のみです。
• 辞書の一覧は、データセットが実際に公開している行と照合され、公開されていないコードは除外されます。source は照合が実行されたかどうかを示し、通知には除外された件数が記載されます。
• query はコードとラベルを照合します。結果はコード順に並べ替えられ、省略がある場合はその旨が示されます（limit は 1～500 の整数、既定値は 50、totalCount は一致件数を示します）。ecnbasic では、within_naics を指定すると TAXSTAT と TYPOP を 1 つの業種に限定できます。

---

census_resolve_geography _ツール

• 名前付きの場所（例：「King County, WA」）は TIGERweb を通じて解決されます。住所は Census Geocoder によって国勢調査区レベルまで解決され、block_group_fips と place_fips が返されます。5 桁の ZIP（または ZIP+4）は、その ZIP Code Tabulation Area（zip code tabulation area）に解決されます
• 州、郡、場所、国勢調査区、ZIP については、geography_type が自動検出されます。大都市圏・小都市圏統計地域、合同統計地域、統合都市、経済上の場所では、geography_type を明示する必要があります。economic place は 8 桁の ecnbasic コード（Seattle 03363000）を返します
• 場所のレベルには国勢調査指定地域が含まれます。この地域は、法人化された場所または郡が完全一致しない場合にのみ、名前だけで検索できます。完全な名前（「Arlington CDP, VA」）を使用するか、geography_type: "place" を指定すると検索できます。省略可能な county_fips は、郡と国勢調査区の解決対象を絞り込みます（住所またはそれ以外のレベルでは county_scope_unsupported が返されます）
• 大文字・小文字は区別されず、州の略称または正式名称を使用できます。また、Saint/St. の違いやアクセント記号の違いは許容されます。New York City の各区は郡に解決されます（「Brooklyn, NY」→ Kings County 047）。この場合、notice が返されます
• 複数の地理情報に一致する名前を指定すると、すべての候補の FIPS コードと州を含む ambiguous_name が返されます。結果には、次のツールで使用できる state_fips（→ parent_fips）と fips_summary（→ geography_fips）が含まれます。統計地域と ZCTA には state_fips が含まれません

---

census_query_data _ツール

• FIPS コードが必要です（地名には census_resolve_geography を使用してください）。geography_fips: "*" を指定すると、親の範囲内にある指定レベルのすべての地理情報が返されます。各行には geography_fips と、全国で一意の geography_geoid が含まれます。ワイルドカードでは GEOID 順に最大 limit 行（デフォルト 50、最大 500）が返されます。offset でページングでき、残りの件数は totalCount と truncated に示されます
• 1 回の呼び出しにつき変数コードは最大 49 個です。ラベル列またはレコード列が追加されるデータセットでは、上限がさらに少なくなります（too_many_variables に最大数が示されます）。不明なコードには variable_not_found が返されます。レベルと親の指定に問題がある場合は、parent_required または parent_not_accepted が返されます。省略可能な tract_fips（6 桁、具体的な county_fips と併用）を指定すると、ブロックグループまたは 10 年ごとの国勢調査ブロックのクエリ対象を 1 つの国勢調査区に絞り込めます
• 省略可能な predicates マップで、business、pep、dec データセット、および acs/acs1/spp をフィルタリングできます（例：{"NAICS2017": "5112"}）。未指定のディメンションには Census のデフォルト値が適用され、各行の applied_filters に示されます。"*" を指定すると、カテゴリごとに 1 行が返され、record にラベルが付けられます。pep/charv は地理情報ごとに複数行を返すため、1 つに絞り込んでください（例：{"MONTH": "7"}）
• ACS のセンチネル値は公開時の意味に置き換えられ、開区間の中央値には open_ended フラグが付きます。cbp、ecnbasic、nonemp では、秘匿値は抑制済みとして報告され、フラグの意味が示されます。estimate が null の場合、値は抑制済み、テキストセル（value として返されます）、または空です
• dec/ddhca と dec/ddhcb では、地理情報の POPGROUP グループは、ファミリー内の 1 つのテーブルにのみ含まれます。no_data のヒントまたは通知に、同じファミリーの他のテーブルが示されます。CENSUS_API_KEY が必要です

---

census_compare_geographies _ツール

• あるレベルのすべての地域、または名前付きの geographies リストに含まれる GEOID／レベルコードのみを順位付けします。within／within_county を指定すると州／郡内に範囲を絞り、全国比較では省略します
• 1つの変数で順位付けします。sort_by（デフォルトは最初のコード。要求したコードでなければならず、そうでない場合は sort_by_not_requested）、sort_dir（デフォルトは desc）、limit（1～500、デフォルトは50）を指定します。totalCount は上限適用前の地域数です。カウント値で順位付けすると、率ではなく規模による順位になります。率で順位付けするには、公表されている割合を使用してください（acs/acs5/subject の S1701_C03_001E、acs/acs5/profile の DP04_0047PE）
• census_query_data と同じ predicates、変数の上限、検証、applied_filters を使用します。複数レコードのデータセット（pep/charv）または "*" の述語は、predicates で1件に絞り込まない限り ambiguous_rows エラーになります。抑制値は同じ理由で末尾に並び、テキスト値は順位付けできません（通知にその旨が記載されます）。CENSUS_API_KEY が必要です

---

機能

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

Census 固有の機能：

• プロセス内の変数キャッシュと設定可能な TTL — データセットと年の組み合わせごとに variables.json を一度取得し、クライアント側で検索します
• 3つの API を使うバックエンド：データクエリには Census Data API、名前付き地域の解決には TIGERweb、住所から国勢調査区への変換には Census Geocoder を使用します
• すべての外部 API 呼び出しで、バックオフを伴う自動再試行を行います
• FIPS の書式設定ヘルパー — ゼロ埋めされた州、郡、国勢調査区のコードを、ツール間でそのまま受け渡せます

エージェントが使いやすい出力：

• ワークフロー指向のツール群 — fips_summary と state_fips が返す値は、次のツールの geography_fips と parent_fips にそのまま渡せます
• 抑制コードをデコード — Census の負のセンチネル値（例：-666666666）や企業データセットの非公開フラグ（例：D）を、生の数値や誤ったゼロではなく、公表されている意味に置き換えて提示します
• エラー時の復旧ヒント — 曖昧な地域名には候補リストを含め、API キーがない場合のエラーには登録 URL を含めます

---

はじめに

公開ホストインスタンス

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

Claude Code の場合：

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

Cline の場合（cline_mcp_settings.json）：

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

Cursor の場合（mcp.json）：

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

Claude Desktop では、「設定」→「コネクタ」からリモートサーバーを追加します。

セルフホスト／ローカル

API キー： api.census.gov/data/key_signup.html で無料のキーを登録してください。変数検索と地域の解決はキーなしで利用できますが、データクエリ（census_query_data、census_compare_geographies）にはキーが必要です。

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

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

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

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

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

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

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

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

前提条件

• Bun v1.4.0 以降（または Node.js v24 以降）。
• Census API キー — api.census.gov/data/key_signup.html で無料登録できます。census_query_data と census_compare_geographies に必要です。他のツールはキーなしで利用できます。

インストール

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

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

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

cd census-mcp-server

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

bun install

4. 環境を設定します：

cp .env.example .env
# edit .env and set CENSUS_API_KEY

---

設定

変数	説明	デフォルト
CENSUS_API_KEY	データクエリに必須です。 api.census.gov/data/key_signup.html で無料登録できます。	—
CENSUS_DEFAULT_YEAR	年が指定されていない場合のデフォルトのビンテージ年です。	2024
CENSUS_VARIABLE_CACHE_TTL_HOURS	データセットと年ごとの variables.json をメモリにキャッシュする時間数です。	24
MCP_TRANSPORT_TYPE	トランスポート：stdio または http。	stdio
MCP_SESSION_MODE	HTTP セッションモード：stateful、stateless、または auto。	stateless
MCP_HTTP_PORT	HTTP サーバーのポートです。	3010
MCP_AUTH_MODE	認証モード：none、jwt、または oauth。	none
MCP_LOG_LEVEL	ログレベル（debug、info、notice、warning、error）。	info
LOG_TOOL_FAILURE_PAYLOADS	失敗したツール呼び出しごとに、引数と結果をログに記録します。キー名によるマスキングを行い、LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES（デフォルトは 16384）で上限を設定します。自由形式の値に含まれるシークレットはマスキングされません。	false
OTEL_ENABLED	OpenTelemetry の計装を有効にします。	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
bun run lint:mcp   # Validate MCP definitions against spec

Docker

docker build -t census-mcp-server .
docker run --rm -e CENSUS_API_KEY=your-key -p 3010:3010 census-mcp-server

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

---

プロジェクト構成

パス	目的
src/index.ts	createApp() のエントリーポイントです。ツールを登録し、サービスを初期化します。
src/config/server-config.ts	Census 固有の環境変数を解析し、Zod で検証します。
src/mcp-server/tools/definitions/	ツール定義（*.tool.ts）です。
src/services/census-api/	Census Data API クライアントです。データクエリ、抑制コードのマッピング、再試行ロジックを扱います。
src/services/geography/	地理情報の解決を行います。TIGERweb による地名検索と、Census Geocoder による住所からトラクトへの変換を扱います。
src/services/variable-cache/	TTL とキーワード検索に対応した、プロセス内の variables.json キャッシュです。
tests/	src/ の構成を反映した Vitest テストです。

---

開発ガイド

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

• ハンドラーは例外をスローし、フレームワークが捕捉します。ツールのロジックでは try/catch を使いません。
• リクエスト単位のログには ctx.log、テナント単位のストレージには ctx.state を使用します。
• 新しいツールは src/mcp-server/tools/definitions/index.ts のバレルを通じて登録します。
• 外部 API 呼び出しはラップします。生データを検証し、ドメイン型に正規化してから出力スキーマを返します。不足しているフィールドを捏造してはいけません。

---

コントリビューション

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

bun run devcheck
bun run test

---

ライセンス

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