# Frankfurter Forex MCP
MCP server in Python for currency rates, conversion, and exchange-rate history using the Frankfurter API.
## Features
- `base_quote`: latest rates from a base currency to one or many targets
- `convert_currency`: converts an amount between two currencies
- `exchange_history`: returns the time series for a currency pair in a date range
- Structured error payloads with `error_code`, `tool`, and `trace_id`
- Retry with exponential backoff for transient upstream failures
## Tech stack
- Python 3.11+
- MCP Python SDK (`mcp`)
- `httpx` async client
- Pydantic v2
- `pytest`, `pytest-asyncio`, `ruff`
## Project structure
```text
src/frankfurter_forex_mcp/
client/frankfurter.py
models/schemas.py
tools/
base_quote.py
convert_currency.py
exchange_history.py
server.py
tests/
```
## Setup
1. Install dependencies:
```bash
uv sync --all-extras
```
2. Copy environment file:
```bash
cp .env.example .env
```
## Run MCP server (stdio)
```bash
uv run python -m frankfurter_forex_mcp.server
```
## Use with MCP Inspector on localhost
The easiest way to expose this server in the local Inspector is using:
```bash
uv run mcp dev src/frankfurter_forex_mcp/server.py
```
This command starts the local Inspector bridge and shows a localhost URL in the terminal.
For a manual Inspector stdio connection flow, see [`.docs/mcp-inspector-guide.md`](.docs/mcp-inspector-guide.md).
## Advanced MCP practices implemented
- Strict request validation with Pydantic before external calls
- Strict external payload validation before response serialization
- Stable JSON error contracts for machine clients
- `stdio`-safe runtime behavior (no stdout logging side effects)
- CI pipeline for linting, testing, and package smoke checks
## Run quality checks
```bash
uv run ruff check .
uv run pytest
```
## CI
GitHub Actions workflow is available at `.github/workflows/ci.yaml`.
