https://github.com/anirbanbasu/frankfurtermcp
A MCP server for the Frankfurter API for currency exchange rates.
https://github.com/anirbanbasu/frankfurtermcp
currency-converter currency-exchange-rates fastmcp finance frankfurter-api mcp mcp-composition mcp-server model-context-protocol model-context-protocol-server
Last synced: 4 months ago
JSON representation
A MCP server for the Frankfurter API for currency exchange rates.
- Host: GitHub
- URL: https://github.com/anirbanbasu/frankfurtermcp
- Owner: anirbanbasu
- License: mit
- Created: 2025-06-07T08:31:11.000Z (4 months ago)
- Default Branch: master
- Last Pushed: 2025-06-08T02:42:46.000Z (4 months ago)
- Last Synced: 2025-06-08T02:43:00.701Z (4 months ago)
- Topics: currency-converter, currency-exchange-rates, fastmcp, finance, frankfurter-api, mcp, mcp-composition, mcp-server, model-context-protocol, model-context-protocol-server
- Language: Python
- Homepage:
- Size: 49.8 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-mcp-servers - **FrankfurterMCP** - MCP server acting as an interface to the Frankfurter API for currency exchange data. `api` `http` `git` `github` (Other)
- awesome-mcp-servers - **FrankfurterMCP** - MCP server acting as an interface to the Frankfurter API for currency exchange data. `api` `http` `git` `github` (Other)
- awesome-mcp-servers - FrankfurterMCP - MCP server acting as an interface to the [Frankfurter API](https://frankfurter.dev/) for currency exchange data. (Community Servers)
README
[](https://www.python.org/downloads/release/python-3120/)
[](#)
[](https://github.com/anirbanbasu/frankfurtermcp/actions/workflows/dependabot/dependabot-updates) [](https://github.com/anirbanbasu/frankfurtermcp/actions/workflows/uv-pytest.yml)
# Frankfurter MCP
[Frankfurter](https://frankfurter.dev/) 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.
| Date | Status | Notes or observations |
|----------|:-------------:|----------------------|
| 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. |
## Installation
The directory where you clone this repository will be referred to as the _working directory_ or _WD_ hereinafter.
Install [uv](https://docs.astral.sh/uv/getting-started/installation/). 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.
```bash
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](https://gofastmcp.com/servers/fastmcp#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](https://www.python-httpx.org/environment_variables/). In addition, `SSL_CERT_FILE` and `SSL_CERT_DIR` can be configured to so that
| Variable | [Default value] and description |
|--------------|----------------|
| `HTTPX_TIMEOUT` | [5.0] The time for the underlying HTTP client to wait, in seconds, for a response. |
| `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. |
| `MCP_SERVER_TRANSPORT` | [streamable-http] The acceptable options are `stdio`, `sse` or `streamable-http`. Given the use-case of running this MCP server as a remotely accessible endpoint, there is no real reason to choose `stdio`. |
| `FRANKFURTER_API_URL` | [https://api.frankfurter.dev/v1] If you are [self-hosting the Frankfurter API](https://hub.docker.com/r/lineofflight/frankfurter), you should change this to the API endpoint address of your deployment. |
## 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.
```bash
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.
```bash
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.
```bash
./.venv/bin/python -m frankfurtermcp.server
```
The MCP endpoint will be available over HTTP at [http://localhost:8000/sse](http://localhost:8000/sse) for the Server Sent Events (SSE) transport, or [http://localhost:8000/mcp](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._
```bash
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](http://localhost:8000/sse) for the Server Sent Events (SSE) transport, or [http://localhost:8000/mcp](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_.
```bash
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._
```bash
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](http://localhost:8000/sse) for the Server Sent Events (SSE) transport, or [http://localhost:8000/mcp](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](https://gofastmcp.com/), check the file [`src/frankfurtermcp/composition.py`](https://github.com/anirbanbasu/frankfurtermcp/blob/master/src/frankfurtermcp/composition.py).
## Contributing
Install [`pre-commit`](https://pre-commit.com/) for Git and [`ruff`](https://docs.astral.sh/ruff/installation/). Then enable `pre-commit` by running the following in the _WD_.
```bash
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`_.
```bash
uv run --group test pytest tests/
```
## License
[MIT](https://choosealicense.com/licenses/mit/).