FrankfurterMCP

What is FrankfurterMCP?

FrankfurterMCP is a Model Context Protocol (MCP) server that acts as an interface to the Frankfurter API, providing access to real-time and historical currency exchange rate data. It allows language model agents to interact with currency exchange functionalities through a standardized protocol.

How to use FrankfurterMCP?

FrankfurterMCP can be used in several ways:

• Server with uv: Install uv and run uv run frankfurtermcp in the working directory. Environment variables can be configured via a .env file or directly in the shell.
• Server with pip: Install the package via pip install frankfurtermcp and run python -m frankfurtermcp.server.
• Server using Docker: Build and run the Docker image using the provided local.dockerfile.
• Dynamic mounting with FastMCP: Integrate FrankfurterMCP into your own MCP server using FastMCP for dynamic composition.

Clients can access FrankfurterMCP through:

• MCP Inspector: A visual tool for testing and debugging MCP servers. Install Node.js and run npx @modelcontextprotocol/inspector uv run frankfurtermcp.
• Claude Desktop, Visual Studio Code: Configure these applications to run FrankfurterMCP as a server using stdio transport.
• Command-line interface (CLI): Use the cli script to explore available tools and their schemas (e.g., uv run cli --help, uv run cli tools-info).

Key Features of FrankfurterMCP

• Currency Exchange Data: Access to latest, historical, and time-series currency exchange rates from the Frankfurter API.
• Model Context Protocol (MCP) Server: Exposes currency exchange functionalities as tools for language model agents.
• Flexible Deployment: Can be run as a standalone server, integrated with FastMCP, or deployed via Docker.
• Configurable: Supports environment variables for host, port, debug mode, log level, HTTP client timeout, SSL verification, and Frankfurter API URL.
• Tooling: Provides a CLI for inspecting available tools and their schemas.
• Supported Tools: Includes tools for getting supported currencies, latest exchange rates, converting currency using latest rates, getting historical exchange rates, and converting currency for a specific date.

Use Cases of FrankfurterMCP

• Language Model Agents: Enables AI agents to perform currency-related tasks, such as providing real-time exchange rates, converting amounts, or analyzing historical currency trends.
• Financial Applications: Can be integrated into applications requiring up-to-date currency exchange information.
• Data Analysis: Facilitates access to historical currency data for financial analysis and research.
• Educational Tools: Can be used in educational settings to demonstrate currency exchange concepts and API interactions.

FAQ about FrankfurterMCP

• What is the Frankfurter API? The Frankfurter API is a service that provides currency exchange rates, historical data, and time series, often sourced from the European Central Bank.

• What is MCP? MCP stands for Model Context Protocol, a protocol designed for exposing tools and functionalities to language model agents.

• How can I configure the Frankfurter API URL? You can set the FRANKFURTER_API_URL environment variable to point to your self-hosted Frankfurter API instance.

• Can I use FrankfurterMCP with self-signed certificates? Yes, you can configure SSL_CERT_FILE and SSL_CERT_DIR environment variables, or set HTTPX_VERIFY_SSL to False (though the latter is not recommended for production).

• How do I see the available tools? You can use the FrankfurterMCP CLI with the tools-info command (e.g., uv run cli tools-info) after starting the server in streamable-http or sse transport mode.

Frankfurter MCP

Frankfurter is a useful API for latest currency exchange rates, historical data, or time series published by sources such as the European Central Bank. Should you have to access the Frankfurter API as tools for language model agents exposed over the Model Context Protocol (MCP), Frankfurter MCP is what you need.

Installation

If your objective is to use the tools available on this MCP server, please refer to the usage > client sub-section below.

The directory where you clone this repository will be referred to as the working directory or WD hereinafter.

Install uv. To install the project with its minimal dependencies in a virtual environment, run the following in the WD. To install all non-essential dependencies (which are required for developing and testing), replace the --no-dev with the --all-groups flag in the following command.

uv sync --no-dev

Environment variables

Following is a list of environment variables that can be used to configure the application. A template of environment variables is provided in the file .env.template.

The following environment variables can be specified, prefixed with FASTMCP_: HOST, PORT, DEBUG and LOG_LEVEL. See global configuration options for FastMCP. Note that on_duplicate_ prefixed options specified as environment variables will be ignored.

The underlying HTTP client also respects some environment variables, as documented in the HTTPX library. In addition, SSL_CERT_FILE and SSL_CERT_DIR can be configured to use self-signed certificates of hosted API endpoint or intermediate HTTP(S) proxy server(s).

Variable	[Default value] and description
HTTPX_TIMEOUT	[5.0] The time for the underlying HTTP client to wait, in seconds, for a response from the Frankfurter API.
HTTPX_VERIFY_SSL	[True] This variable can be set to False to turn off SSL certificate verification, if, for instance, you are using a proxy server with a self-signed certificate. However, setting this to False is advised against: instead, use the SSL_CERT_FILE and SSL_CERT_DIR variables to properly configure self-signed certificates.
FAST_MCP_HOST	[0.0.0.0] This variable specifies which host the MCP server must bind to unless the server transport (see below) is set to stdio.
FAST_MCP_PORT	[8000] This variable specifies which port the MCP server must listen on unless the server transport (see below) is set to stdio.
MCP_SERVER_TRANSPORT	[stdio] The acceptable options are stdio, sse or streamable-http. However, in the .env.template, the default value is set to streamable-http.
MCP_SERVER_INCLUDE_METADATA_IN_RESPONSE	[True] An experimental feature to include additional metadata to the MCP type TextContent that wraps the response data from each tool call. The additional metadata, for example, will include (as of June 21, 2025) the API URL of the Frankfurter server that is used to obtain the responses.
FRANKFURTER_API_URL	[https://api.frankfurter.dev/v1] If you are self-hosting the Frankfurter API, you should change this to the API endpoint address of your deployment.

Usage

The following sub-sections illustrate how to run the Frankfurter MCP as a server and how to access it from MCP clients.

Server

While running the server, you have the choice to use stdio transport or HTTP options (sse or the newer streamable-http).

Using default settings and MCP_SERVER_TRANSPORT set to sse or streamable-http, the MCP endpoint will be available over HTTP at http://localhost:8000/sse for the Server Sent Events (SSE) transport, or http://localhost:8000/mcp for the streamable HTTP transport.

If you want to run Frankfurter MCP with stdio transport and the default parameters, execute the commands below without using the .env.template file.

Server with uv

Optional: Copy the .env.template file to a .env file in the WD, to modify the aforementioned environment variables, if you want to use anything other than the default settings. Or, on your shell, you can export the environment variables that you wish to modify.

Run the following in the WD to start the MCP server.

uv run frankfurtermcp

Server with pip from PyPI package

Add this package from PyPI using pip in a virtual environment (possibly managed by conda or pyenv) and then start the server by running the following.

Optional: Add a .env file with the contents of the .env.template file if you wish to modify the default values of the aforementioned environment variables. Or, on your shell, you can export the environment variables that you wish to modify.

pip install frankfurtermcp
python -m frankfurtermcp.server

Server using Docker

There are two Dockerfiles provided in this repository.

• local.dockerfile for containerising the Frankfurter MCP server.
• smithery.dockerfile for deploying to Smithery AI, which you do not have to use.

To build the image, create the container and start it, run the following in WD. Choose shorter names for the image and container if you prefer.

If you change the port to anything other than 8000 in .env.template, do remember to change the port number references in the following command. Instead of passing all the environment variables using the --env-file option, you can also pass individual environment variables using the -e option.

docker build -t frankfurtermcp -f local.dockerfile .
docker create -p 8000:8000/tcp --env-file .env.template --expose 8000 --name frankfurtermcp-container frankfurtermcp
docker start frankfurtermcp-container

Upon successful build and container start, the MCP server will be available over HTTP at http://localhost:8000/sse for the Server Sent Events (SSE) transport, or http://localhost:8000/mcp for the streamable HTTP transport.

Dynamic mounting with FastMCP

To see how to use the MCP server by mounting it dynamically with FastMCP as part of your own MCP server, check the file src/frankfurtermcp/composition.py.

Cloud hosted servers

The currently available cloud hosted options are as follows.

• Glama.AI: https://glama.ai/mcp/servers/@anirbanbasu/frankfurtermcp
• Smithery.AI: https://smithery.ai/server/@anirbanbasu/frankfurtermcp

Client access

This sub-section explains ways for a client to connect and test the FrankfurterMCP server. A command-line interface (CLI) is also provided for testing, which is explained in a later sub-section.

The official MCP visual inspector

The MCP Inspector is an official Model Context Protocol tool that can be used by developers to test and debug MCP servers. This is the most comprehensive way to explore the MCP server.

To use it, you must have Node.js installed. The best way to install and manage node as well as packages such as the MCP Inspector is to use the Node Version Manager (or, nvm). Once you have nvm installed, you can install and use the latest Long Term Release version of node by executing the following.

nvm install --lts
nvm use --lts

Following that (install and) run the MCP Inspector by executing the following in the WD.

npx @modelcontextprotocol/inspector uv run frankfurtermcp

This will create a local URL at port 6274 with an authentication token, which you can copy and browse to on your browser. Once on the MCP Inspector UI, press Connect to connect to the MCP server. Thereafter, you can explore the tools available on the server.

Claude Desktop, Visual Studio, and so on

The server entry to run with stdio transport that you can use with systems such as Claude Desktop, Visual Studio Code, and so on is as follows.

{
    "command": "uv",
    "args": [
        "run",
        "frankfurtermcp"
    ]
}

Instead of having frankfurtermcp as the last item in the list of args, you may need to specify the full path to the script, e.g., WD/.venv/bin/frankfurtermcp. Likewise, instead of using uv, you could also have the following JSON configuration with the path properly substituted for python3.12, for instance such as WD/.venv/bin/python3.12.

{
    "command": "python3.12",
    "args": [
        "-m",
        "frankfurtermcp.server"
    ]
}

List of available tools

The following table lists the names of the tools as exposed by the FrankfurterMCP server. It does not list the tool(s) exposed through the composition example. The descriptions shown here are for documentation purposes, which may differ from the actual descriptions exposed over the model context protocol.

Name	Description
get_supported_currencies	Get a list of currencies supported by the Frankfurter API.
get_latest_exchange_rates	Get latest exchange rates in specific currencies for a given base currency.
convert_currency_latest	Convert an amount from one currency to another using the latest exchange rates.
get_historical_exchange_rates	Get historical exchange rates for a specific date or date range in specific currencies for a given base currency.
convert_currency_specific_date	Convert an amount from one currency to another using the exchange rates for a specific date.

The required and optional arguments for each tool are not listed in the following table for brevity but are available to the MCP client over the protocol.

FrankfurterMCP command-line interface (CLI)

You may also use the CLI provided with FrankfurterMCP to explore the tools of the MCP server. For example, to see the detailed schema for a particular tool, you can do so using the tools-info commmand from the command line interface. The command line interface is available as the script cli. You can invoke its help to see the available commands as follows.

uv run cli --help

This will produce an output similar to the screenshot below.

Before calling the tools-info command, you MUST have the server running in streamable-http or sse transport mode, preferably locally, e.g., by invoking MCP_SERVER_TRANSPORT=streamable-http uv run frankfurtermcp. A successful call of the tools-info command will generate an output similar to the screenshot shown below.

Alternative to the tools-info command, you can also run call the llamaindex-tools-list command to display the names of the tools without the respective function schemas. This functionality is provided only to optionally demonstrate that the LlamaIndex MCP client can read the tools list from this MCP server. In order for this to function, you must install LlamaIndex MCP client by calling uv sync --extra opt. The output of calling this command will look like the following.

Contributing

Install pre-commit for Git and ruff. Then enable pre-commit by running the following in the WD.

pre-commit install

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Testing

To run the provided test cases, execute the following. Add the flag --capture=tee-sys to the command to display further console output.

Note that for the tests to succeed, the environment variable MCP_SERVER_TRANSPORT must be set to either sse or streamable-http. If not set, it will default to stdio and the tests will fail.

MCP_SERVER_TRANSPORT=streamable-http uv run --group test pytest tests/

License

MIT.

Project status

Following is a table of some updates regarding the project status. Note that these do not correspond to specific commits or milestones.

Date	Status	Notes or observations
June 27, 2025	active	Successful remote deployments on Glama.AI and Smithery.AI.
June 13, 2025	active	Added LlamaIndex tool listing for demonstration only. (The --all-extras flag is necessary to install LlamaIndex, which is not installed by default.)
June 9, 2025	active	Added containerisation, support for self-signed, proxies.
June 8, 2025	active	Added dynamic composition.
June 7, 2025	active	Added tools to cover all the functionalities of the Frankfurter API.
June 7, 2025	active	Project started.