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

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:

uv sync --all-extras

2. Copy environment file:

cp .env.example .env

Run MCP server (stdio)

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:

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.

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

uv run ruff check .
uv run pytest

CI

GitHub Actions workflow is available at .github/workflows/ci.yaml.