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

Setup

1. Install dependencies:

2. Copy environment file:

Run MCP server (stdio)

Use with MCP Inspector on localhost

The easiest way to expose this server in the local Inspector is using:

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

CI

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