# eurostat-mcp

An [MCP](https://modelcontextprotocol.io) server that exposes the [Eurostat Statistics API](https://ec.europa.eu/eurostat/web/main/data/web-services) so that LLM assistants can discover, explore, and retrieve official EU statistical data.

## Tools

| Tool | Description |
|---|---|
| `search_datasets` | Search the Eurostat catalogue by keyword |
| `get_dataset_dimensions` | Inspect the dimension structure and valid filter codes for a dataset |
| `get_dataset_data` | Retrieve data with optional filters (geo, time, unit, etc.) |

### Typical workflow

```
1. search_datasets("GDP")                          # find dataset codes
2. get_dataset_dimensions("nama_10_gdp")           # discover dimensions & valid codes
3. get_dataset_data("nama_10_gdp",                 # pull the numbers
       geo=["FR","DE","ES"],
       last_time_period=5,
       filters={"unit": ["CLV10_MEUR"], "na_item": ["B1GQ"]})
```

## Resources

| URI | Description |
|---|---|
| `eurostat://datasets/{query}` | Browse datasets matching a keyword |
| `eurostat://dataset/{code}/dimensions` | Dimension structure for a specific dataset |

## Prompts

| Prompt | Description |
|---|---|
| `explore_topic` | Step-by-step plan to find EU statistics on a topic |
| `compare_countries` | Retrieve and compare an indicator across EU countries |

---

## Getting started

### Prerequisites

- Python 3.11+
- [uv](https://docs.astral.sh/uv/) (recommended) or pip

### Install locally

```bash
git clone https://github.com/dcerecedo/eurostat-mcp.git
cd eurostat-mcp

# with uv
uv pip install -e .

# or with pip
pip install -e .
```

### Run (stdio — for Claude Desktop / claude-code)

```bash
eurostat-mcp
# or
eurostat-mcp --transport stdio
```

### Run (SSE — for network clients)

```bash
eurostat-mcp --transport sse
# listens on http://0.0.0.0:8000/sse by default
```

Environment variables to override defaults:

| Variable | Default | Description |
|---|---|---|
| `MCP_TRANSPORT` | `stdio` | Transport: `stdio`, `sse`, or `streamable-http` |
| `MCP_HOST` | `0.0.0.0` | Bind host (SSE / HTTP only) |
| `MCP_PORT` | `8000` | Bind port (SSE / HTTP only) |

---

## Docker

Build and run with Docker Compose (exposes port 8001):

```bash
docker compose up --build
```

The server will be available at `http://localhost:8001/sse`.

To run the image directly:

```bash
docker build -t eurostat-mcp .
docker run -p 8001:8001 eurostat-mcp
```

---

## Connecting to Claude

### Claude Desktop

Add the following to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "eurostat": {
      "command": "eurostat-mcp"
    }
  }
}
```

### Claude Code (stdio)

```bash
claude mcp add eurostat -- eurostat-mcp
```

### Claude Code (SSE — when running via Docker or SSE server)

```json
{
  "mcpServers": {
    "eurostat": {
      "type": "sse",
      "url": "http://localhost:8001/sse"
    }
  }
}
```

A ready-to-use `.mcp.json` file with the SSE config is included in this repo.

---

## License

MIT