Skip to main content
Glama
lcfranca

Frankfurter Forex MCP

by lcfranca
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

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

Related MCP server: FrankfurterMCP

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

  1. 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.

Available Tools

3 tools
base_quoteC

Get latest exchange rates from one base currency to multiple target currencies.

ParametersJSON Schema
NameRequiredDescriptionDefault
baseYes
targetsYes

TDQS

C2.8/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool retrieves 'latest exchange rates,' implying a read-only operation, but doesn't specify data sources, update frequency, rate limits, error handling, or authentication requirements. For a tool with zero annotation coverage, this leaves critical behavioral traits undocumented.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that front-loads the core functionality. There's no wasted wording, and it directly communicates the tool's purpose without unnecessary details. This is appropriately concise for a simple data retrieval tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity (2 parameters, no annotations, no output schema), the description is incomplete. It doesn't address parameter details, behavioral traits, or output format. While conciseness is good, the lack of contextual information makes it inadequate for an agent to use the tool effectively without additional assumptions.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, meaning the input schema provides no descriptions for parameters. The description mentions 'base currency' and 'target currencies,' which loosely map to the 'base' and 'targets' parameters, but doesn't explain expected formats (e.g., currency codes like USD), constraints, or examples. It adds minimal semantic value beyond what's inferred from parameter names.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Get latest exchange rates from one base currency to multiple target currencies.' It specifies the verb ('Get'), resource ('latest exchange rates'), and scope (one-to-many conversion). However, it doesn't explicitly differentiate from sibling tools like 'convert_currency' or 'exchange_history', which likely handle different aspects of currency data.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus its siblings ('convert_currency' and 'exchange_history'). It doesn't mention alternatives, prerequisites, or exclusions. The agent must infer usage from the tool name and description alone, which is insufficient for clear decision-making.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

convert_currencyC

Convert a monetary amount from one currency to another.

ParametersJSON Schema
NameRequiredDescriptionDefault
amountYes
from_currencyYes
to_currencyYes

TDQS

C2.8/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool converts currency but doesn't add any context about rate sources, accuracy, limitations, or potential errors. For a tool with no annotations, this leaves significant gaps in understanding its operational behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, clear sentence with zero waste. It's appropriately sized and front-loaded, efficiently conveying the core purpose without unnecessary details.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (currency conversion with 3 parameters), no annotations, no output schema, and 0% schema coverage, the description is incomplete. It lacks details on behavior, parameters, and output, making it inadequate for reliable agent use without additional context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the schema provides no parameter descriptions. The description mentions 'monetary amount' and 'currencies' but doesn't elaborate on parameter meanings, formats (e.g., currency codes like USD), or constraints. It adds minimal value beyond the schema's structure.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose with a specific verb ('convert') and resource ('monetary amount from one currency to another'). It distinguishes the core function well, though it doesn't explicitly differentiate from sibling tools like 'base_quote' or 'exchange_history', which might offer related currency functions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools, prerequisites, or specific contexts for use, leaving the agent to infer usage based on the generic purpose alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

exchange_historyC

Get an exchange-rate time series for a currency pair and date interval.

ParametersJSON Schema
NameRequiredDescriptionDefault
startYes
endYes
from_currencyYes
to_currencyYes

TDQS

C2.8/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool retrieves data ('Get'), implying a read-only operation, but doesn't mention any behavioral traits such as rate limits, authentication needs, data freshness, error conditions, or response format. This is inadequate for a tool with 4 parameters and no output schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, well-structured sentence that efficiently conveys the core purpose without any wasted words. It's front-loaded with the main action and resource, making it easy to parse quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (4 parameters, no annotations, no output schema), the description is incomplete. It lacks details on parameter usage, behavioral context, output format, and differentiation from siblings. This leaves significant gaps for an agent to understand how to invoke the tool effectively.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema description coverage is 0%, so the description must compensate. It mentions 'currency pair and date interval', which hints at parameters like 'from_currency', 'to_currency', 'start', and 'end', but doesn't explain their semantics, formats (e.g., date strings like YYYY-MM-DD), or constraints. This adds minimal value beyond the bare parameter names in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose with a specific verb ('Get') and resource ('exchange-rate time series'), specifying the target data (currency pair and date interval). It distinguishes from sibling tools like 'base_quote' and 'convert_currency' by focusing on historical time-series data rather than current rates or conversions. However, it doesn't explicitly contrast with siblings, so it's not a perfect 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives like 'base_quote' or 'convert_currency'. It mentions the data type (time series) but doesn't specify use cases, prerequisites, or exclusions. This leaves the agent with minimal context for tool selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 3 tool updatesv0.1.0
    • First observedbase_quote
    • First observedconvert_currency
    • First observedexchange_history
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.3/5.0

Scored across 3 tools

Disambiguation5/5

Each tool has a clearly distinct purpose with no overlap: base_quote retrieves latest rates from one base to multiple targets, convert_currency handles specific amount conversions, and exchange_history provides historical time series data. An agent can easily differentiate these functions without confusion.

Naming Consistency4/5

The naming follows a consistent pattern with two tools using snake_case (base_quote, exchange_history) and one using a verb_noun style (convert_currency), which is a minor deviation. All names are descriptive and readable, but the mix of conventions slightly reduces consistency.

Tool Count5/5

With 3 tools, this is well-scoped for a forex server, covering core operations: real-time rates, currency conversion, and historical data. Each tool earns its place without bloat or thinness, making it appropriate for the domain.

Completeness4/5

The toolset covers key forex functionalities—real-time rates, conversions, and historical data—with no major gaps. Minor gaps might include advanced features like currency lists or metadata, but agents can work effectively with the provided tools for common workflows.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Currency Converter MCP

    wesbos
    F
    license
    C
    quality
    F
    maintenance
    An MCP server providing real-time currency conversion and exchange rate data through the Frankfurter API, enabling users to convert currencies, fetch latest or historical rates, and list available currencies.
    4
    35
    -

  • plinth-fx-mcp

    plinthkit
    -
    license
    Not graded
    quality
    Not graded
    maintenance
    MCP server that provides real exchange-rate data from the European Central Bank, including latest rates, currency conversion, historical rates, and time series.
    -