Skip to content

Commit e204673

Browse files
scka-descka-de
committed
feat: ecb-mcp v0.1.0 — 8 MCP tools for ECB data
MCP server giving AI agents direct access to the European Central Bank SDMX API. Zero configuration, no API key required. Tools: - get_exchange_rates: EUR reference rates for 40+ currencies - get_interest_rates: ECB key policy rates (MRO, deposit, marginal) - get_yield_curve: AAA sovereign yield curve (3M-30Y) - get_inflation: HICP inflation (euro area or per country) - get_money_supply: monetary aggregates M1/M2/M3 - convert_currency: currency conversion via ECB rates - search_datasets: keyword search across 100+ ECB datasets - explain_dataset: dataset structure and valid dimension values 143 tests (116 unit + 27 integration against live ECB API).
1 parent 422bcb5 commit e204673

46 files changed

Lines changed: 6901 additions & 0 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.gitignore‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
node_modules/
2+
dist/
3+
*.tsbuildinfo
4+
.env
5+
CLAUDE.md

‎CHANGELOG.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# Changelog
2+
3+
## 0.1.0 (2026-03-29)
4+
5+
Initial release.
6+
7+
### Tools
8+
9+
- `get_exchange_rates` — EUR reference rates for 40+ currencies (daily, monthly, annual)
10+
- `get_interest_rates` — ECB key policy rates (MRO, deposit facility, marginal lending)
11+
- `get_yield_curve` — AAA government bond yield curve (3M to 30Y)
12+
- `get_inflation` — HICP inflation (euro area or per country)
13+
- `get_money_supply` — Monetary aggregates M1, M2, M3 (outstanding or growth rate)
14+
- `convert_currency` — Currency conversion via ECB rates (including cross-rates via EUR)
15+
- `search_datasets` — Keyword search across 100+ ECB datasets
16+
- `explain_dataset` — Dataset structure, dimensions, and valid values for any ECB dataset
17+
18+
### Features
19+
20+
- Zero configuration — no API key, no registration
21+
- Direct access to the ECB SDMX 2.1 REST API
22+
- Human-readable output optimized for LLM consumption
23+
- Rate limiting (1 req/sec) to be a good API citizen
24+
- Retry with exponential backoff on server errors

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 scka-de
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 187 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,187 @@
1+
# ecb-mcp
2+
3+
European Central Bank data for AI agents. Exchange rates, interest rates, yield curves, inflation, money supply, and 100+ more datasets from the ECB — directly inside Claude, Cursor, Windsurf, or any MCP client.
4+
5+
No API key. No registration. No config. Just `npx ecb-mcp`.
6+
7+
[![npm version](https://img.shields.io/npm/v/ecb-mcp.svg)](https://www.npmjs.com/package/ecb-mcp)
8+
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
9+
10+
## Why
11+
12+
The ECB publishes 100+ statistical datasets via a free, public API — exchange rates for 40+ currencies, key interest rates, yield curves, HICP inflation, monetary aggregates, banking statistics, and much more.
13+
14+
But the API uses SDMX, a format nobody memorizes. You need to know dataflow IDs, dimension key structures, and query syntax just to get a single number.
15+
16+
ecb-mcp translates natural questions into the right SDMX queries. Your AI agent asks "What's the current EUR/USD rate?" and gets a clean answer from live ECB data. No SDMX knowledge required.
17+
18+
## Quick Start
19+
20+
Add to your MCP client config:
21+
22+
```json
23+
{
24+
"mcpServers": {
25+
"ecb": {
26+
"command": "npx",
27+
"args": ["-y", "ecb-mcp"]
28+
}
29+
}
30+
}
31+
```
32+
33+
That's it. No API key, no environment variables, no account creation.
34+
35+
### Where to add this config
36+
37+
- **Claude Desktop:** `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows)
38+
- **Claude Code:** `claude mcp add ecb-mcp -- npx -y ecb-mcp`
39+
- **Cursor:** Settings > MCP Servers
40+
- **Windsurf:** `~/.windsurf/config.json`
41+
42+
## What you can ask
43+
44+
Once installed, just ask your AI agent questions in natural language:
45+
46+
> "What's the current EUR/USD exchange rate?"
47+
>
48+
> "Show me ECB interest rate changes since 2022"
49+
>
50+
> "What's the eurozone inflation rate?"
51+
>
52+
> "Convert 5000 USD to GBP using ECB rates"
53+
>
54+
> "What's the 10-year euro area government bond yield?"
55+
>
56+
> "How has M3 money supply grown over the past year?"
57+
>
58+
> "What ECB datasets are available about bank lending?"
59+
>
60+
> "Explain the structure of the EXR dataset"
61+
62+
## Tools
63+
64+
### get_exchange_rates
65+
66+
EUR reference rates for 40+ currencies. Daily, monthly, or annual. The same rates used by European institutions and businesses.
67+
68+
```
69+
"What's the EUR/USD rate?"
70+
"Show me EUR/GBP rates for the last 30 days"
71+
"EUR/JPY monthly averages for 2024"
72+
```
73+
74+
### get_interest_rates
75+
76+
The ECB's key policy rates — the ones that move markets and drive eurozone monetary policy.
77+
78+
```
79+
"What is the current ECB deposit facility rate?"
80+
"Show me the history of ECB rate changes"
81+
"When did the ECB last change the main refinancing rate?"
82+
```
83+
84+
### get_yield_curve
85+
86+
Euro area government bond yield curve. AAA-rated sovereign spot rates from 3 months to 30 years.
87+
88+
```
89+
"What's the 10-year euro area yield?"
90+
"Show me the 2-year yield over the past 6 months"
91+
"Compare 5Y and 10Y yields since January"
92+
```
93+
94+
### get_inflation
95+
96+
HICP inflation — the official eurozone inflation measure. Available for the euro area as a whole or individual countries.
97+
98+
```
99+
"What's the current eurozone inflation rate?"
100+
"Germany's inflation over the past year"
101+
"Compare inflation in France vs Spain"
102+
```
103+
104+
### get_money_supply
105+
106+
Euro area monetary aggregates (M1, M2, M3). Outstanding amounts or annual growth rates.
107+
108+
```
109+
"What's the current M3 money supply?"
110+
"M1 growth rate over the past year"
111+
"How has M3 evolved since 2020?"
112+
```
113+
114+
### convert_currency
115+
116+
Convert any amount between currencies using official ECB reference rates. Supports EUR-direct, inverse, and cross-currency conversions (e.g., USD to GBP via EUR triangulation).
117+
118+
```
119+
"Convert 1000 EUR to USD"
120+
"How much is 500 GBP in JPY?"
121+
"What was 10000 USD worth in CHF on 2025-01-15?"
122+
```
123+
124+
### search_datasets
125+
126+
Search across all 100+ ECB statistical datasets by keyword. The ECB publishes far more than exchange rates — banking statistics, balance of payments, government debt, payment systems, insurance data, and much more.
127+
128+
```
129+
"What ECB datasets are about bank lending?"
130+
"Find datasets related to government debt"
131+
"What data does the ECB publish about payments?"
132+
```
133+
134+
### explain_dataset
135+
136+
Understand any ECB dataset's structure — its dimensions, valid values, and how to query it. This is the key to unlocking the full 100+ datasets beyond the built-in tools.
137+
138+
```
139+
"Explain the EXR dataset structure"
140+
"What dimensions does the BSI dataset have?"
141+
"What are the valid currency codes?"
142+
```
143+
144+
## Data Source
145+
146+
All data comes directly from the [ECB Data Portal API](https://data.ecb.europa.eu/help/api/overview) (SDMX 2.1 REST).
147+
148+
- No intermediary, no proxy — live data from the European Central Bank
149+
- No authentication or API key required
150+
- Exchange rates updated daily at 16:00 CET
151+
- Other datasets updated at various frequencies (monthly, quarterly)
152+
153+
## Configuration
154+
155+
ecb-mcp works with zero configuration. Optional settings:
156+
157+
| Environment Variable | Default | Description |
158+
|---|---|---|
159+
| `ECB_API_URL` | `https://data-api.ecb.europa.eu/service` | API base URL. Only change this if you're proxying the ECB API. |
160+
| `DEBUG` | — | Set to any value to enable debug logging to stderr. |
161+
162+
## Development
163+
164+
```bash
165+
git clone https://github.com/scka-de/ecb-mcp.git
166+
cd ecb-mcp
167+
npm install
168+
npm test # unit tests (fixtures, no API calls)
169+
INTEGRATION=true npm test # integration tests (live ECB API)
170+
npm run build # compile to dist/
171+
npm run dev # run in dev mode
172+
npm run lint # check code style
173+
```
174+
175+
## How It Works
176+
177+
ecb-mcp translates your AI agent's natural language questions into SDMX series key queries against the ECB API. For example, when Claude asks for the EUR/USD rate, ecb-mcp:
178+
179+
1. Builds the SDMX key: `D.USD.EUR.SP00.A`
180+
2. Fetches CSV from `https://data-api.ecb.europa.eu/service/data/EXR/D.USD.EUR.SP00.A?format=csvdata`
181+
3. Parses the response and returns clean, human-readable data
182+
183+
For dataset discovery, ecb-mcp fetches and parses XML metadata from the ECB's structure definition endpoints, letting your agent explore all 100+ datasets without knowing SDMX.
184+
185+
## License
186+
187+
MIT

‎biome.json‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
{
2+
"$schema": "https://biomejs.dev/schemas/1.9.0/schema.json",
3+
"organizeImports": {
4+
"enabled": true
5+
},
6+
"linter": {
7+
"enabled": true,
8+
"rules": {
9+
"recommended": true,
10+
"suspicious": {
11+
"noConsole": "error"
12+
}
13+
}
14+
},
15+
"formatter": {
16+
"enabled": true,
17+
"indentStyle": "space",
18+
"indentWidth": 2
19+
},
20+
"files": {
21+
"ignore": ["dist/**", "node_modules/**"]
22+
}
23+
}

0 commit comments

Comments
 (0)