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 need to access the Frankfurter API as tools for language model agents exposed over the Model Context Protocol (MCP), Frankfurter MCP is what you need.

Project status

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

Installation

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 essential dependencies in a virtual environment, run the following in the WD. To install all non-essential dependencies (which are required for developing and testing), add the --all-extras flag to the following command.

uv sync

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_SERVER_: HOST, PORT, DEBUG and LOG_LEVEL. See key 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 so that

Usage (with pip)

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.

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

Usage (self-hosted server using uv)

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

If you want to run it without uv, assuming that the appropriate virtual environment has been created in the .venv within the WD, you can start the server calling the following.

./.venv/bin/python -m frankfurtermcp.server

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. To exit the server, use the Ctrl+C key combination.

Usage (self-hosted server using Docker)

There are two Dockerfiles provided in this repository.

• pypi.dockerfile for using the version of frankfurtermcp on PyPI.
• local.dockerfile for using the latest version, which can contain your edits to the code if you do make edits.

Using the version available on PyPI

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.

docker build -f pypi.dockerfile -t frankfurtermcp-pypi .
docker create -p 8000:8000/tcp --name frankfurtermcp-pypi-container frankfurtermcp-pypi
docker start frankfurtermcp-pypi-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.

Using the local version

Before containerising the local version, you must build the project distribution wheel file and ensure that only one such wheel file exists. To do so, run the following in WD.

rm -fR dist
uv build

Once the distribution has been built, to build the Docker image, create the container and start it, run the following in WD. Choose shorter names for the image and container if you prefer.

docker build -f local.dockerfile -t frankfurtermcp-local .
docker create -p 8000:8000/tcp --name frankfurtermcp-local-container frankfurtermcp-local
docker start frankfurtermcp-local-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.

Usage (dynamic mounting with FastMCP)

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

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, or not set at all, in which case it will default to streamable-http.

uv run --group test pytest tests/

License

MIT.