FrankfurterMCP

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.

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

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

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.

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.

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.

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 is one Dockerfile provided in this repository.

• Dockerfile for using the latest version, which can contain your edits to the code if you do make edits.

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.

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.

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.

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.

Client access

The following subsections explain ways for a client to connect and test the FrankfurterMCP server.

The official 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.

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

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.

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

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.

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

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.

License

MIT.