e-Stat MCP Server

estat-mcp

e-Stat (政府統計の総合窓口) API client and MCP server for Japanese government statistics.

📝 日本語チュートリアル: Claude に聞くだけで GDP や CPI がわかる (Zenn)

What is this?

estat-mcp provides programmatic access to Japan's official statistics portal (e-Stat), which hosts 3,000+ statistical tables covering population, economy, prices, labor, agriculture, and regional data. It exposes these as both a Python async client and an MCP server for AI assistants.

• Search statistics by keyword (人口, GDP, CPI, etc.)
• Retrieve metadata to understand table structure (表章事項, 分類事項, 時間軸, 地域)
• Fetch statistical data with automatic pagination for large datasets
• Type-safe Pydantic models with Polars/pandas DataFrame export
• Rate limiting built-in for API compliance
• MCP server with 4 tools for Claude Desktop and other AI tools

Quick Start

Installation

pip install estat-mcp
# or
uv add estat-mcp

Get an API Key

Register (free) at e-Stat API and set:

export ESTAT_APP_ID=your_app_id_here

30-Second Example

import asyncio
from estat_mcp import EstatClient

async def main():
    async with EstatClient() as client:
        # Search for population statistics
        tables = await client.search_stats("人口")
        print(tables[0].name)  # 人口推計

        # Get metadata
        meta = await client.get_meta(tables[0].id)
        print(f"Time periods: {[t.name for t in meta.time_items]}")

        # Fetch data (Tokyo, 2024)
        data = await client.get_data(
            tables[0].id,
            cd_area="13000",   # Tokyo
            cd_time="2024000", # 2024
            limit=100
        )
        
        # Export as DataFrame
        df = data.to_polars()
        print(df)

asyncio.run(main())

CLI Quick Start

# Test API connectivity
estat-mcp test

# Search for CPI statistics
estat-mcp search "消費者物価指数" --limit 10

# Fetch data for a table
estat-mcp data 0003410379 --cd-area 13000 --format table

# Start MCP server
estat-mcp serve

MCP Server

Add to your AI tool's MCP config:

<details> <summary><b>Claude Desktop</b> (~⁠/Library/Application Support/Claude/claude_desktop_config.json)</summary>

{
  "mcpServers": {
    "estat": {
      "command": "uvx",
      "args": ["estat-mcp", "serve"],
      "env": {
        "ESTAT_APP_ID": "your_app_id_here"
      }
    }
  }
}

</details> <details> <summary><b>Cursor</b> (~⁠/.cursor/mcp.json)</summary>

{
  "mcpServers": {
    "estat": {
      "command": "uvx",
      "args": ["estat-mcp", "serve"],
      "env": {
        "ESTAT_APP_ID": "your_app_id_here"
      }
    }
  }
}

</details>

Then ask your AI: "日本の人口統計を教えて" or "東京の最新CPIは？"

Available MCP Tools

Tool	Description
search_statistics	キーワードで統計テーブルを検索
get_statistic_meta	テーブル構造（表章事項・分類事項・時間軸・地域）を取得
get_statistic_data	統計データを取得（フィルタ・ページネーション対応）
get_all_statistic_data	全ページ自動取得（max_pages制限付き）

Python API

Search → Metadata → Data Flow

import asyncio
from estat_mcp import EstatClient

async def main():
    async with EstatClient() as client:
        # 1. Search for statistics tables
        tables = await client.search_stats("消費者物価指数", limit=5)
        # → [StatsTable(id="0003410379", name="消費者物価指数", ...), ...]

        stats_id = tables[0].id

        # 2. Get metadata to understand structure
        meta = await client.get_meta(stats_id)
        print(f"Table items: {[i.name for i in meta.table_items]}")
        print(f"Time periods: {[t.name for t in meta.time_items]}")
        print(f"Areas: {[a.name for a in meta.area_items]}")

        # 3. Fetch data with filters
        data = await client.get_data(
            stats_id,
            cd_area="13000",      # Tokyo only
            cd_time="2024000",    # 2024 only
            limit=1000
        )

        # 4. Export to DataFrame
        df = data.to_polars()
        print(df)

asyncio.run(main())

Automatic Pagination

For large datasets, use get_all_data() to automatically fetch all pages:

# Fetch up to 10 pages (safety limit)
all_data = await client.get_all_data(
    stats_id,
    max_pages=10,
    cd_cat01="100"  # Filter by classification
)
print(f"Fetched {len(all_data.values)} / {all_data.total_count} records")

Polars Export

# Requires: pip install estat-mcp[polars]
d