bls-mcp-server

---

概要

米国労働統計局の労働統計データ：雇用、失業率、賃金、インフレ。SeriesID を解読する代わりに、平易な言葉で系列を検索できます。全期間の履歴または最新の値を取得し、複数の系列にまたがる大量の結果に対して SQL を実行できます。

ツール

ツール	説明
bls_list_surveys	BLS の調査プログラム（CPI、CPS、CES、JOLTS、PPI、OEWS、…）を、コード、説明、計算サポートの有無とともに一覧表示します。
bls_search_series	自然言語、調査、地域、キーワードで BLS 系列カタログを検索し、分かりにくい SeriesID を特定します。
bls_get_series	SeriesID で 1～50 件の BLS 系列の時系列データを取得します。年の範囲と期間ごとの変化率の計算を任意で指定できます。
bls_get_latest	1 つ以上の BLS 系列について、最も新しい観測値を 1 件返します。
bls_dataframe_describe	bls_get_series または bls_dataframe_query によって登録されたキャンバスデータフレームを一覧表示します。データの出所、TTL、行数、列スキーマを確認できます。CANVAS_PROVIDER_TYPE=duckdb の場合に利用できます。
bls_dataframe_query	bls_get_series または以前の register_as によって登録されたキャンバスデータフレームに対して SELECT を実行します。JOIN、集計、ウィンドウ関数、CTE に対応しています。CANVAS_PROVIDER_TYPE=duckdb の場合に利用できます。
bls_dataframe_drop	名前でキャンバスデータフレームを削除します。CANVAS_PROVIDER_TYPE=duckdb かつ BLS_DATAFRAME_DROP_ENABLED=true の場合に利用できます。デフォルトでは TTL によってクリーンアップされます。

機能リファレンス

bls_list_surveys _tool

• 任意の category を指定すると、調査プログラムを分野で絞り込み、コード、名称、計算サポートフラグ（allowsNetChange、allowsPercentChange、hasAnnualAverages）を返します。
• BLS 調査 API を利用し、月次でキャッシュします。年平均のサポートは参考情報です。実際に返された行については、bls_get_series の annualAverageRows を参照してください。

---

bls_search_series _tool

• テキストまたは SeriesID で検索できます。任意で survey、area（地域、タイトル、または SeriesID の部分文字列）、seasonal_adjustment を指定できます。空のフィルターは省略されます。limit は 1～50（デフォルトは 10）で、offset によるページネーションに対応します。地域フィルターがない場合、地名ではデコードされた地域との一致が優先されます。同じスコアの場合、各優先グループ内では全国系列が優先されます。完全一致する SeriesID が最上位に表示されます。
• デコードされた SeriesID、タイトル、frequency、個別に指定可能な startYear、endYear、endPeriod のカバレッジ（例：1982–2005 Q04）を返します。カバレッジはカタログのスナップショットを示すもので、観測値が連続していることを示すものではありません。truncated が true の間は nextOffset に従って取得を続けてください。capped: true の場合、totalCount は下限値であり、ページネーションは FTS の候補プールで終了します。
• API クォータを消費せずにオフラインの LABSTAT インデックスを検索します。OE/OEWS は BLS_CATALOG_INCLUDE_OES でオプトインできます。インデックス化されていない調査も SeriesID で取得できます。

---

bls_get_series _tool

• 1 回の呼び出しで 1～50 個の SeriesID を取得できます。start_year／end_year は最大 20 年の期間を指定でき、calculations と annual_average は任意です。開始年のみを指定した場合、終了年は現在の年または開始年 + 19 のいずれか早い方になります。終了年のみの指定は拒否されます。1 回のバッチで API クエリを 1 回消費します。計算は調査のサポート状況に依存します（CPI／PPI が返すのは変化率のみです）。
• available とともに観測値を返し、欠損値を示す生の - センチネルを保持します。複数系列を含むバッチでは、有効な系列も返します。拡張情報には、適用された年の範囲、計算、年平均の行が含まれます。
• 結果が大きい場合、CANVAS_PROVIDER_TYPE=duckdb であれば dataset.name に出力します。それ以外の場合は canvas_unavailable を返し、対象期間を狭めるよう求めます。

---

bls_get_latest _tool

• 最大 50 個の SeriesID の最新の観測値を取得します（推奨は 10 個以下）。各 ID で API クエリを 1 回消費します。複数系列をより効率的にまとめて取得するには、bls_get_series を使用してください。
• 成功した項目を results[] で、系列ごとの失敗項目を failed[] で返します。latestObservation.available により、公表値と BLS の欠損値センチネルを区別できます。

---

bls_dataframe_describe _tool

• 任意の name を指定すると、登録済みの 1 つのデータフレームについて説明を返します。指定しない場合は、テナントのアクティブなデータフレームを一覧表示します。CANVAS_PROVIDER_TYPE=duckdb が必要です。
• ソースツール、クエリパラメーター、行数、TTL（created_at／expires_at）、column_schema を返します。BLS の列は NULL 許容です。登録済みクエリの型のうち、キャンバスの型セットに含まれないもの（DECIMAL、HUGEINT、SMALLINT、リスト）は VARCHAR として報告されます。期限切れのエントリーは、キャンバスの削除が成功したときに削除されます。

---

bls_dataframe_query _tool

• 登録済みテーブルに対して、JOIN、集計、ウィンドウ関数、または CTE を使った SELECT を 1 つ実行します。row_limit のデフォルトは 1000、上限は 10000 です。書き込み、外部ファイルの読み取り、システムカタログへのアクセスは拒否されます。
• エンジン設定（current_setting、current_schema、current_schemas、in_search_path）と query_table は拒否されます。query() が受け付けるのは、最大 4 階層まで再帰的に検証されるプレーンな SQL 文字列リテラル 1 つです。計算によって生成された SQL 文字列は拒否されます。分析ではステージング済みのテーブルを直接参照してください。
• BLS API クォータを消費せずに行を返します。任意の register_as を指定すると、新しい TTL で結果をステージングし、連続した分析に利用できます。CANVAS_PROVIDER_TYPE=duckdb が必要です。

---

bls_dataframe_drop _ツール

• 必須のnameは、削除するデータフレームを指定します。CANVAS_PROVIDER_TYPE=duckdbかつBLS_DATAFRAME_DROP_ENABLED=trueの場合にのみ利用できます。デフォルトではTTLによってクリーンアップされます。
• テーブルが見つからない場合はdropped: falseを返します。削除に失敗すると、再試行可能なcanvas_drop_failedを返し、データフレームは登録されたままになります。

機能

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

BLS固有の機能：

• リトライ／バックオフと日次クォータ追跡に対応したBLS API v2クライアント
• LABSTATフラットファイルを対象としたオフラインの系列カタログ検索。オンディスクのSQLite/FTS5ストアとしてインデックス化されており、検索時にAPIクォータを消費しません。OES/OEWS賃金調査（約600万系列）の利用はBLS_CATALOG_INCLUDE_OESでオプトインできます
• クォータ超過、データベースのロック、計算非対応など、BLS固有の障害モードに対応した型付きエラーコントラクト
• BLS独自のサーバー側フラグを使った期間ごとの純変化率／変化率計算。BLSが公開している数値と一致します
• 大規模な複数系列の結果セットに対応するオプションのDataCanvasスピルオーバー（DuckDB）。APIを再クエリせずにスキーマを確認し、SQLでアクセスできます

エージェントに適した出力：

• データの出所 — キャンバスにスピルされた結果には、行数と有効期限に加えてdataset.nameハンドルが含まれます。bls_search_seriesはeffectiveQuery、catalogSize、FTS候補プールがcappedだったかどうかも返します
• 部分的な失敗への対応 — bls_get_latestは、バッチ全体を失敗させるのではなく、成功したresults[]とともに項目ごとのfailed[]（seriesId + error）を返します。bls_get_seriesは、同じバッチ内の別のSeriesIDが無効または空でも、有効な系列を保持します
• 判別可能な出力 — すべての観測値には、BLSの欠損値を示す-に対するavailableブール値が含まれるため、呼び出し元は生の値を解析せず、型付きフィールドで分岐できます
• 次のアクションがわかる通知 — enrichment.noticeは、結果が空の場合、キャンバスへのスピルオーバー、データが利用できない場合について、具体的な次の手順（例：SeriesIDの確認にbls_search_seriesを使用する）を説明します

はじめに

公開ホストインスタンス

公開インスタンスはhttps://bls-labor.caseyjhand.com/mcpで利用できます。インストールは不要です。Streamable HTTPを介して、任意のMCPクライアントから接続します：

{
  "mcpServers": {
    "bls-labor-mcp-server": {
      "type": "streamable-http",
      "url": "https://bls-labor.caseyjhand.com/mcp"
    }
  }
}

セルフホスト／ローカル

以下をMCPクライアントの設定ファイルに追加してください。無料のBLS APIキーを使うと、1日あたり500件のクエリが利用できます。bls.gov/developersで登録してください。キーがなくても、サーバーは1日あたり25件のリクエストで動作します。

{
  "mcpServers": {
    "bls-labor-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/bls-labor-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "BLS_API_KEY": "your-key-here"
      }
    }
  }
}

またはnpxを使用する場合（Bunは不要です）：

{
  "mcpServers": {
    "bls-labor-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/bls-labor-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "BLS_API_KEY": "your-key-here"
      }
    }
  }
}

またはDockerを使用する場合：

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

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

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

前提条件

• Bun v1.4.0以降（またはNode.js v24以降）。
• 無料のBLS API v2キー。bls.gov/developersで登録してください。1日あたり500件のクエリが利用できます。キーがなくても、サーバーは1日あたり25件のリクエストで動作します。

インストール

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

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

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

cd bls-labor-mcp-server

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

bun install

4. 環境を設定します：

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

設定

すべての設定は、起動時に src/config/server-config.ts の Zod スキーマを使用して検証されます。

変数	説明	デフォルト
BLS_API_KEY	BLS v2 API キーです。任意です。キーがない場合は 1 日あたり 25 リクエスト、キーがある場合は 1 日あたり 500 リクエストです。bls.gov/developers から無料で登録できます。	—
BLS_BASE_URL	BLS API v2 のベース URL です。	https://api.bls.gov/publicAPI/v2
BLS_CATALOG_BASE_URL	LABSTAT フラットファイルのベース URL です。ローカルミラーを指定する場合は変更してください。	https://download.bls.gov/pub/time.series
BLS_CATALOG_DB_PATH	ディスク上の SQLite カタログインデックスです。必要に応じてクエリされ、再起動後も保持されます。空の場合はインメモリ DB が使用され、起動のたびに再収集されます。コンテナではここにボリュームをマウントしてください。	.cache/bls-catalog.db
BLS_CATALOG_CACHE_TTL_HOURS	カタログの鮮度を保つ時間（時間単位）です。インデックスがこの期間を過ぎると再収集されます。起動時と実行中の毎時に確認されます。	168（7 日）
BLS_CATALOG_INCLUDE_OES	OES/OEWS 賃金調査（約 600 万系列／約 1.2 GB、初回の収集には数分かかります）を含めます。デフォルトでは無効ですが、OES 系列は ID を指定して取得できます。	false
BLS_OBSERVATIONS_MIRROR_ENABLED	ライブ API の代わりに、ローカルの SQLite ミラーから観測値を提供します（初回のブートストラップが必要です。下記を参照してください）。	false
BLS_DATASET_TTL_SECONDS	キャンバスに登録されたテーブルのデータフレームごとの TTL（秒単位）です。	86400（24 時間）
BLS_DATAFRAME_DROP_ENABLED	bls_dataframe_drop を公開します。デフォルトでは TTL によってクリーンアップされます。	false
CANVAS_PROVIDER_TYPE	大規模な結果セット向けの DataCanvas 表形式スピルオーバーを有効にするには、duckdb に設定します。	none
MCP_TRANSPORT_TYPE	トランスポートです。stdio または http を指定します。	stdio
MCP_HTTP_PORT	HTTP サーバーのポートです。	3010
MCP_SESSION_MODE	セッションモードです。このサーバーでは stateless を使用します。有効なスキーマ値は auto、stateful、stateless です。スキーマのデフォルトである auto は stateful に解決されます。	stateless
MCP_AUTH_MODE	認証モードです。none、jwt、oauth のいずれかを指定します。	none
MCP_LOG_LEVEL	ログレベル（RFC 5424）です。	info
LOGS_DIR	ログファイル用ディレクトリです（Node.js のみ）。	<project-root>/logs
OTEL_ENABLED	OpenTelemetry インストルメンテーションを有効にします。	false
OTEL_EXPORTER_OTLP_ENDPOINT	トレースとメトリクス用の OTLP ベース URL です。シグナル固有のエンドポイントが設定されている場合は、そちらが優先されます。	—
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT	オプトイン方式の OTLP ログエンドポイントです。ベース URL を設定してもログエクスポートは有効になりません。	—
LOG_TOOL_FAILURE_PAYLOADS	失敗した呼び出しの引数と結果を、キー名に基づいて秘匿化してログに記録します。自由形式の値に含まれるシークレットは秘匿化されません。	false
LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES	ログに記録する失敗ペイロードごとの UTF-8 バイト数の上限です。	16384

オプションで指定できる上書き設定の全一覧は、.env.example を参照してください。

観測データのミラーリング（任意）

大量のワークロードでは、オプトイン方式のローカルミラーを使うと、bls_get_series / bls_get_latest は BLS API の代わりに組み込みの SQLite ストアからデータを取得し、1 日あたり 500 件のクォータ上限を回避できます。デフォルトでは無効です。有効にするには、次の手順を実行します。

1. BLS_OBSERVATIONS_MIRROR_ENABLED=true を設定し、.env.example の BLS_OBSERVATIONS_MIRROR_* 変数を確認します。

2. 初回のブートストラップを別途実行します。LABSTAT の観測データ一式をダウンロードするため、時間がかかる場合があります。

   node dist/services/bls-observations/subprocess.js --init
   

ミラーはカタログの調査リストにあるすべての調査を収集します。OE も含まれ、BLS_CATALOG_INCLUDE_OES の設定は問いません。そのため CM と CI も対象となり、cm.data.* / ci.data.* ファイルは約 55 MB です。増分更新では、ミラーの最終更新以降に公開されたファイルのみを読み込みます。そのため、CM と CI が追加される前にブートストラップされたミラーも、BLS が次に各ファイルを公開した時点で取り込みます。それまでは、ライブ API へのフォールバックが有効なら、該当する系列はライブ API から取得されます。ブートストラップが完了するまでは、リクエストはライブ API にフォールバックします（ただし、BLS_OBSERVATIONS_MIRROR_FALLBACK_LIVE=false の場合を除きます）。ライブ API へのフォールバックに失敗した場合（クォータ超過、BLS に接続できない場合など）でも、ミラーから提供された系列は返されます。また、enrichment.notice には、提供できなかった各 SeriesID と、失敗の理由および復旧方法が記載されます。ミラーの行には BLS の計算値は含まれません。calculations: true を指定した場合、ミラーから提供された系列には計算フィールドが含まれず、enrichment.calculationsApplied は false となり、通知にその系列が記載されます。HTTP トランスポートでは、BLS_OBSERVATIONS_MIRROR_REFRESH_CRON のスケジュールに従って増分更新が実行されます。コンテナでは、BLS_OBSERVATIONS_MIRROR_PATH に永続ボリュームをマウントしてください。

既存のミラーのアップグレード。 センチネル行の保存が導入される前にブートストラップされたミラーには、BLS が欠損値マーカー - とともに公開する期間が含まれていません。このようなミラーを開くと、同期チェックポイントが一度クリアされるため、次回の更新ですべての LABSTAT ファイルが再読み込みされ、該当するデータが補完されます。更新を実行する以外にオペレーターの作業は必要ありませんが、全件の読み込みと同じ時間がかかります。ミラーはその間も引き続きデータを提供します。

サーバーの実行

ローカル開発

• ビルドと実行：

  # 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
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec
  

Docker

docker build -t bls-labor-mcp-server .
docker run --rm -e BLS_API_KEY=your-key -e MCP_TRANSPORT_TYPE=http -p 3010:3010 bls-labor-mcp-server

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

プロジェクト構成

ディレクトリ	用途
src/index.ts	createApp() のエントリーポイントです。ツールを登録し、サービスを初期化します。
src/config	Zod を使った、サーバー固有の環境変数の解析と検証です。
src/mcp-server/tools	ツール定義（*.tool.ts）です。
src/services/bls-api	BLS API v2 サービスです。一括取得、最新値の GET、調査メタデータを提供します。
src/services/bls-catalog	LABSTAT フラットファイルのカタログです。オフラインの系列インデックスと検索機能を提供します。
src/services/bls-observations	任意の LABSTAT 観測データミラーです。組み込み SQLite ストア、取り込み処理、更新用サブプロセスを提供します。
src/services/bls-periods	API とミラーの両方で共有される、年平均期間のセマンティクス（M13/Q05/S03）です。
src/services/canvas-bridge	DataCanvas ブリッジです。データフレームの登録、SQL ゲート、ライフサイクル管理を提供します。
docs/design.md	ツールの全仕様、サービスアーキテクチャ、エラー契約を記載しています。
tests/	src/ に対応するユニットテストと統合テストです。

開発ガイド

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

• ハンドラーは例外をスローし、フレームワークが捕捉します。ツールのロジック内では try/catch を使いません。
• リクエスト単位のログには ctx.log を、テナント単位のストレージには ctx.state を使用します。
• bls_search_series は基点となるツールです。API ツールより前に呼び出すワークフローを設計してください。
• BLS API の呼び出しはラップします。生データを検証し、ドメイン型に正規化してから、出力スキーマに従って返します。欠落フィールドを決して捏造しないでください。

貢献

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

bun run devcheck
bun run test

ライセンス

Apache-2.0 — 詳細はLICENSEをご覧ください。