Frankfurter

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 just to manage project tasks.

Install uv. To install the project with its minimal dependencies in a virtual environment, run the just install in the WD. To install all non-essential dependencies (which are required for developing and testing), run just install-all instead.

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. Note that the default values listed in the table below are not always the same as those in the .env.template file.

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

Frankfurter MCP will cache calls to the Frankfurter API to improve performance. The cache happens with two different strategies. For API calls whose responses do not change for certain parameters, e.g., historical rate lookup, a least recently used (LRU) cache is used. For API calls whose responses do change, e.g., latest rate lookup, a time-to-live (TTL) cache is used with a default time-to-live set to 15 minutes. The cache parameters can be adjusted using the environment variables, see below.

Variable	[Default value] and description
LOG_LEVEL	[INFO] The level for logging. Changing this level also affects the log output of other dependent libraries that may use the same environment variable. See valid values at Python logging documentation.
HTTPX_TIMEOUT	[5.0] The time for the underlying HTTP client to wait, in seconds, for a response from the Frankfurter API. The acceptable range of values is between 5.0 and 60.0.
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	[localhost] This variable specifies which host the MCP server must bind to unless the server transport (see below) is set to stdio. Note that running the server to bind to any IP by specifying 0.0.0.0 poses a security threat. Such a setting should only be used in demo environments.
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.
CORS_MIDDLEWARE_ALLOW_ORIGINS	["localhost", "127.0.0.1"] This variable specifies Cross-Origin Resource Sharing (CORS) allowed origins for the MCP server unless the server transport (see below) is set to stdio. You must set it to "*" explicitly (and you will get a warning by doing so) if you want to test this server over an HTTP transport using the MCP inspector described below.
MCP_SERVER_TRANSPORT	[stdio] The acceptable options are stdio, sse or streamable-http. However, in the .env.template, the default value is set to stdio.
MCP_SERVER_INCLUDE_METADATA_IN_RESPONSE	[True] This specifies if additional metadata will be included with the MCP response from each tool call. The additional metadata, for example, will include the API URL of the Frankfurter server, amongst others, 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.
LRU_CACHE_MAX_SIZE	[1024] The maximum size of the least recently used (LRU) cache for API calls. The acceptable range of values is between 128 and 65536.
TTL_CACHE_MAX_SIZE	[256] The maximum size of the time-to-live (TTL) cache for API calls. The acceptable range of values is between 64 and 16384.
TTL_CACHE_TTL_SECONDS	[900] The time limit, in seconds, of the time-to-live (TTL) cache for API calls. The acceptable range of values is between 60 and 3600.
UVICORN_LIMIT_CONCURRENCY	[100] The maximum number of concurrent connections the server will accept. This helps prevent resource exhaustion from too many simultaneous connections. Only applies when using HTTP transports (sse or streamable-http). The acceptable range of values is between 10 and 10000.

| UVICORN_TIMEOUT_KEEP_ALIVE | [60] The timeout in seconds for keeping idle connections alive. Idle connections will be closed after this period to free up resources. Only applies when using HTTP transports (sse or streamable-http). The acceptable range of values is between 60 and 300. | | UVICORN_TIMEOUT_GRACEFUL_SHUTDOWN | [5] The timeout in seconds for graceful shutdown. The server will wait this long for active connections to complete before forcefully shutting down. Only applies when using HTTP transports (sse or streamable-http). The acceptable range of values is between 5 and 60. | | RATE_LIMIT_MAX_REQUESTS_PER_SECOND | [10.0] The maximum number of requests allowed per second using a token bucket algorithm. This implements rate limiting to prevent API abuse and ensure fair resource allocation. The acceptable range of values is between 1.0 and 10000.0. | | RATE_LIMIT_BURST_CAPACITY | [20] The burst capacity for the rate limiter, allowing short bursts of requests above the per-second limit. This provides flexibility for legitimate usage patterns while still protecting against sustained high request rates. The acceptable range of values is between 2x and 5x the RATE_LIMIT_MAX_REQUESTS_PER_SECOND value. | | REQUEST_SIZE_LIMIT_BYTES | [102400] The maximum size in bytes for HTTP request bodies (default 100KB). Requests exceeding this limit will be rejected with a 413 status code. This prevents memory exhaustion attacks from large payloads. Only applies when using HTTP transports (sse or streamable-http). The acceptable range of values is between 10240 (10KB) and 524288 (512KB). | | DOCKER_TMPFS_SIZE_MB | [100] The size in megabytes for the temporary filesystem (/tmp) when running in Docker with read-only root filesystem. This temporary storage is used for runtime file operations. Increase this value if the application requires more temporary storage for caching or processing large datasets. Only relevant when deploying with Docker Compose. |

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

---

README truncated. View full README on GitHub.