<div align="center">

🇪🇺 eurostat-mcp-suite

The Unified Model Context Protocol (MCP) Server for Eurostat Statistics & EU Data Analysis

Seamlessly search, query, and analyze 8,900+ official European Union statistical datasets via MCP.
Supports SDMX 3.0, SDMX 2.1 Comext (International Trade), DuckDB In-Memory SQL Canvas, NUTS Regional Levels, CSV Exports, Resources, and Prompts.

</div>

---

🌟 Overview

eurostat-mcp-suite is a unified, high-performance MCP server designed to provide AI Agents (Claude Desktop, Cursor, Roo Code, Antigravity CLI, Windsurf, Goose, Zed) with complete access to official Eurostat data.

It combines all capabilities into one robust, clean architecture:

1. Full API Coverage: Connects to both Eurostat SDMX 3.0 (economy, demography, health, energy) and SDMX 2.1 Comext (international trade with DS- prefixes).
2. DuckDB SQL Dataframe Canvas: Stages complete datasets into an in-memory DuckDB database so AI agents can execute read-only SELECT queries without blowing context window token limits.
3. NUTS Regional Filtering: Filter geographic observations by NUTS regional levels (aggregate, country, nuts1, nuts2, nuts3).
4. Catalogue Discovery: Tokenized search with cursor pagination and Eurostat theme tree navigation.
5. Local CSV Exporting: Export single or batch datasets directly to local CSV files.
6. Native Resources & Prompts: Standardized eurostat:// URI resources and guided analytical workflows.

---

⚡ Agent Auto-Installation Prompt

You can copy and paste the prompt below directly to your AI Assistant (Cursor, Roo Code, Antigravity CLI, Windsurf, Claude) to let it automatically configure and verify eurostat-mcp-suite:

Please read the instructions from https://github.com/ManoloZocco/eurostat-mcp-suite and automatically install the Eurostat MCP Suite server for my environment:
1. Detect my OS (macOS/Windows/Linux) and current client editor (Claude Desktop, Cursor, Roo Code, VS Code, Windsurf, AGY).
2. Check if Python 3.10+ and `uv` (or `pip`) are available.
3. Clone https://github.com/ManoloZocco/eurostat-mcp-suite.git to a persistent directory if not present.
4. Add `eurostat-mcp-suite` to my client's MCP configuration file (e.g. claude_desktop_config.json, mcp_config.json, settings.json).
5. Verify that the server starts successfully and test `search_datasets("GDP")`.

---

🧰 Available Tools (12 Tools)

🔍 Discovery & Catalogue Navigation

Tool	Description
search_datasets(query, limit, cursor)	Search Eurostat catalogue by keyword with tokenized matching & cursor pagination
browse_themes(theme_code)	Drill down Eurostat top-level statistical themes (Economy, Population, Trade, Energy, etc.)
list_popular_datasets(category)	List pre-curated high-value Eurostat datasets by domain

📊 Metadata & Data Retrieval

Tool	Description
get_dataset_info(dataset_id)	Inspect dataset title, dimensions, observation count, and sample values
get_dimension_values(dataset_id, dimension_code, nuts_level)	List valid codes for a dimension with optional NUTS regional filtering (country, nuts1, nuts2, nuts3)
query_dataset(dataset_id, filters, nuts_level, since_period, until_period, last_n_periods, limit)	Query decoded statistical observations with OBS_FLAG status markers

🦆 In-Memory DuckDB SQL Canvas

Tool	Description
download_dataset_to_sql(dataset_id, table_name, filters)	Download complete dataset into an in-memory SQL table for high-speed analysis
sql_query(query)	Run read-only SQL SELECT queries across staged DuckDB tables
list_staged_tables()	List currently staged SQL tables and row counts
describe_table(table_name)	Inspect table schema and sample rows

📁 Local File Export

Tool	Description
export_to_csv(dataset_id, filepath, filters)	Save dataset observations directly to a local CSV file
export_multiple_datasets(dataset_ids, output_dir)	Batch export multiple datasets to a target directory

---

🔗 Resources & Prompts

📦 MCP Resources

• eurostat://datasets/{query}: Live search resource matching keywords.
• eurostat://dataset/{code}/dimensions: Dimension structure resource for a dataset.
• eurostat://themes: Root theme tree resource.
• eurostat://popular: Pre-curated popular datasets list resource.

💡 MCP Prompts

• explore_topic(topic): Guided step-by-step workflow to analyze any European statistical topic.
• compare_countries(indicator_dataset, countries): Template for cross-country EU comparative analysis.
• trade_analysis(trade_dataset, reporter): Template for EU international trade & Comext statistical analysis.

---

🚀 Installation & Configuration

Prerequisites

• Python 3.10+
• uv (Recommended, curl -LsSf https://astral.sh/uv/install.sh | sh) or pip

---

1. Claude Desktop

Add the following to your claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

With uv (recommended):

{
  "mcpServers": {
    "eurostat-suite": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/eurostat-mcp-suite",
        "run",
        "server.py"
      ]
    }
  }
}

With standard python:

{
  "mcpServers": {
    "eurostat-suite": {
      "command": "python",
      "args": [
        "/path/to/eurostat-mcp-suite/server.py"
      ]
    }
  }
}

---

2. Cursor IDE

1. Open Cursor Settings -> Features -> MCP.
2. Click + Add New MCP Server.
3. Set Name: eurostat-suite
4. Set Type: command
5. Set Command: uv --directory /path/to/eurostat-mcp-suite run server.py

Alternatively, add to your Cursor .cursor/mcp.json:

{
  "mcpServers": {
    "eurostat-suite": {
      "command": "uv",
      "args": ["--directory", "/path/to/eurostat-mcp-suite", "run", "server.py"]
    }
  }
}

---

3. VS Code (Roo Code / Cline / MCP Extension)

In your VS Code settings.json or Roo Code / Cline MCP settings (cline_mcp_settings.json):

{
  "mcpServers": {
    "eurostat-suite": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/eurostat-mcp-suite",
        "run",
        "server.py"
      ]
    }
  }
}

---

4. Windsurf / Codeium

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "eurostat-suite": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/eurostat-mcp-suite",
        "run",
        "server.py"
      ]
    }
  }
}

---

5. Antigravity CLI / AGY

Run:

agy mcp add eurostat-suite -- command uv --directory /path/to/eurostat-mcp-suite run server.py

---

6. Goose CLI

Run:

goose mcp add eurostat-suite -- command uv --directory /path/to/eurostat-mcp-suite run server.py

---

📖 Usage Examples

Example 1: High-Speed GDP Analysis via DuckDB SQL Canvas

User: "Download the annual GDP dataset nama_10_gdp and run a SQL query to show average GDP for Germany, France, and Italy over the last 5 years."

Agent steps:
1. download_dataset_to_sql(dataset_id="nama_10_gdp", table_name="gdp_table")
2. sql_query("SELECT geo, geo_label, AVG(value) as avg_gdp FROM gdp_table WHERE geo IN ('DE', 'FR', 'IT') GROUP BY geo, geo_label ORDER BY avg_gdp DESC")

Example 2: International Trade Analysis (Comext SDMX 2.1)

User: "Query EU extra-trade statistics for dataset DS-045409."

Agent steps:
1. get_dataset_info("DS-045409")
2. query_dataset(dataset_id="DS-045409", filters={"reporter": ["EU27_2020"]}, limit=50)

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.