anirbanbasu-frankfurtermcp

Frankfurter MCP

Frankfurter 是一个实用的 API，可提供欧洲央行等来源发布的最新货币汇率、历史数据或时间序列。如果你需要通过模型上下文协议（MCP），将 Frankfurter API 作为工具提供给语言模型 Agent 使用，那么 Frankfurter MCP 正是你需要的。

安装

如果你希望使用此 MCP 服务提供的工具，请参阅下文“用法”中的“客户端”小节。

此处将你克隆此代码库的目录称为_工作目录_或 WD。

安装 just 以管理项目任务。

安装 uv。要在虚拟环境中安装项目及其最少依赖项，请在 WD 中运行 just install。要安装所有非必需依赖项（开发和测试所需），请改为运行 just install-all。

环境变量

以下是可用于配置应用的环境变量列表。文件 .env.template 中提供了环境变量模板。请注意，下表列出的默认值与 .env.template 文件中的默认值并不总是相同。

以下环境变量可以通过添加 FASTMCP_ 前缀来指定：HOST、PORT、DEBUG 和 LOG_LEVEL。

底层 HTTP 客户端也支持一些环境变量，详见 HTTPX 库文档。此外，还可以配置 SSL_CERT_FILE 和 SSL_CERT_DIR，以使用托管 API 端点或中间 HTTP(S) 代理服务的自签名证书。

Frankfurter MCP 会缓存对 Frankfurter API 的调用以提升性能。缓存采用两种不同的策略。对于响应不会因某些参数而变化的 API 调用，例如历史汇率查询，会使用最近最少使用（LRU）缓存。对于响应会发生变化的 API 调用，例如最新汇率查询，则使用生存时间（TTL）缓存，默认生存时间设为 15 分钟。可以通过环境变量调整缓存参数，见下文。

变量	[默认值] 和说明
LOG_LEVEL	[INFO] 日志级别。更改此级别也会影响可能使用相同环境变量的其他依赖库的日志输出。有效值请参阅 Python 日志记录文档。
HTTPX_TIMEOUT	[5.0] 底层 HTTP 客户端等待 Frankfurter API 响应的时间，以秒为单位。可接受的值范围为 5.0 到 60.0。
HTTPX_VERIFY_SSL	[True] 如果你使用带有自签名证书的代理服务等，可将此变量设为 False 以关闭 SSL 证书验证。但是，不建议将其设为 False：应改用 SSL_CERT_FILE 和 SSL_CERT_DIR 变量正确配置自签名证书。
FAST_MCP_HOST	[localhost] 除非服务传输方式（见下文）设为 stdio，否则此变量用于指定 MCP 服务必须绑定的主机。请注意，将服务绑定到任意 IP（指定 0.0.0.0）会带来安全风险。此设置仅应在演示环境中使用。
FAST_MCP_PORT	[8000] 除非服务传输方式（见下文）设为 stdio，否则此变量用于指定 MCP 服务必须监听的端口。
CORS_MIDDLEWARE_ALLOW_ORIGINS	["localhost", "127.0.0.1"] 除非服务传输方式（见下文）设为 stdio，否则此变量用于指定 MCP 服务允许的跨源资源共享（CORS）源。若要使用下文所述的 MCP 检查器通过 HTTP 传输测试此服务，必须显式将其设为 "*"（这样做会收到警告）。
MCP_SERVER_TRANSPORT	[stdio] 可接受的选项为 stdio、sse 或 streamable-http。不过，在 .env.template 中，默认值设为 stdio。
MCP_SERVER_INCLUDE_METADATA_IN_RESPONSE	[True] 此变量用于指定是否在每次工具调用的 MCP 响应中包含额外元数据。例如，额外元数据会包含用于获取响应的 Frankfurter 服务 API URL 等信息。
FRANKFURTER_API_URL	[https://api.frankfurter.dev/v1] 如果你在自托管 Frankfurter API，应将此变量更改为你的部署的 API 端点地址。
LRU_CACHE_MAX_SIZE	[1024] API 调用的最近最少使用（LRU）缓存的最大容量。可接受的值范围为 128 到 65536。
TTL_CACHE_MAX_SIZE	[256] API 调用的存活时间（TTL）缓存的最大容量。可接受的值范围为 64 到 16384。
TTL_CACHE_TTL_SECONDS	[900] API 调用的存活时间（TTL）缓存的时限，以秒为单位。可接受的值范围为 60 到 3600。
UVICORN_LIMIT_CONCURRENCY	[100] 服务接受的最大并发连接数。这有助于防止过多的同时连接耗尽资源。仅适用于使用 HTTP 传输方式（sse 或 streamable-http）时。可接受的值范围为 10 到 10000。
UVICORN_TIMEOUT_KEEP_ALIVE	[60] 保持空闲连接的超时时间，以秒为单位。超过此时间后将关闭空闲连接以释放资源。仅适用于使用 HTTP 传输方式（sse 或 streamable-http）时。可接受的值范围为 60 到 300。
UVICORN_TIMEOUT_GRACEFUL_SHUTDOWN	[5] 优雅关闭的超时时间，以秒为单位。服务将在此时间内等待活动连接完成，然后强制关闭。仅适用于使用 HTTP 传输方式（sse 或 streamable-http）时。可接受的值范围为 5 到 60。
RATE_LIMIT_MAX_REQUESTS_PER_SECOND	[10.0] 使用令牌桶算法时每秒允许的最大请求数。此功能通过限制速率来防止 API 滥用，并确保公平分配资源。可接受的值范围为 1.0 到 10000.0。
RATE_LIMIT_BURST_CAPACITY	[20] 限流器的突发容量，允许短时间内的请求数超过每秒限制。这能在防止持续高请求率的同时，灵活适应合理的使用模式。可接受的值范围为 RATE_LIMIT_MAX_REQUESTS_PER_SECOND 值的 2 到 5 倍。
REQUEST_SIZE_LIMIT_BYTES	[102400] HTTP 请求正文的最大字节数（默认 100KB）。超过此限制的请求将被拒绝，并返回 413 状态码。此设置可防止大型负载导致内存耗尽。仅适用于使用 HTTP 传输方式（sse 或 streamable-http）时。可接受的值范围为 10240（10KB）到 524288（512KB）。
DOCKER_TMPFS_SIZE_MB	[100] 使用只读根文件系统在 Docker 中运行时，临时文件系统（/tmp）的大小，以 MB 为单位。此临时存储用于运行时文件操作。如果应用需要更多临时存储来缓存或处理大型数据集，可增大此值。仅在使用 Docker Compose 部署时适用。

用法

以下小节说明如何将 Frankfurter MCP 作为服务运行，以及如何通过 MCP 客户端访问它。

服务

运行服务时，可以选择使用 stdio 传输方式，或使用 HTTP 选项（sse 或较新的 streamable-http）。

使用默认设置，并将 MCP_SERVER_TRANSPORT 设为 sse 或 streamable-http 时，MCP 端点将通过 HTTP 提供：Server Sent Events（SSE）传输方式对应 http://localhost:8000/sse，可流式传输的 HTTP 传输方式对应 http://localhost:8000/mcp。

如果想使用 stdio 传输方式和默认参数运行 Frankfurter MCP，请执行以下命令，无需使用 .env.template 文件。

使用 uv 运行服务

可选：将 .env.template 文件复制为 WD 中的 .env 文件，以修改上述环境变量（如果不想使用默认设置）。或者，也可以在 shell 中导出要修改的环境变量。

在 WD 中运行以下命令以启动 MCP 服务。

uv run frankfurtermcp

使用来自 PyPI 的软件包和 pip 运行服务

在虚拟环境中使用 pip 从 PyPI 安装此软件包（可由 uv、pyenv 或 conda 管理），然后运行以下命令启动服务。

可选：如果想修改上述环境变量的默认值，可以添加一个包含 .env.template 文件内容的 .env 文件。或者，也可以在 shell 中导出要修改的环境变量。

pip install frankfurtermcp
python -m frankfurtermcp.server

使用 Docker 部署服务

本仓库提供了一个 Dockerfile：local.dockerfile，用于将 Frankfurter MCP 服务容器化。首先，将 .env.template 复制为 .env 文件。然后，根据需要修改 .env 文件中的以下变量。

• FASTMCP_HOST：设为 0.0.0.0，以允许外部访问容器。这仅用于本地测试，不建议用于生产部署。
• CORS_MIDDLEWARE_ALLOW_ORIGINS：设为 *，以允许来自任意来源的外部访问 MCP 服务。如果要通过 HTTP 传输使用 MCP Inspector 测试服务，则需要此设置；不建议用于生产部署。

要构建镜像、创建容器并使用 Docker Compose 启动容器，请在_WD_中运行以下命令。

如果将 .env 中的端口改为 8000 以外的值，请记得修改 docker-compose.yml 中的端口号。

注意：所需的最低 Docker Compose 版本为 2.24.0。运行 docker compose version 可查看版本。如果版本较旧，请更新 Docker Desktop，以获取最新的 Docker Compose。此外，后端必须支持 BuildKit。

docker compose up --build

要在分离模式（后台）下运行，请添加 -d 标志：

docker compose up -d --build

要停止容器：

docker compose down

要运行容器并使用本地 Frankfurter API 服务，请运行以下命令。添加 -d 标志即可在分离模式下运行。查看 local_api.env.template 文件，了解用于本地 API 服务的可选环境变量。

注意：首次启动时，本地 Frankfurter API 可能需要一些时间来获取更新的汇率。后续运行时，本地 Frankfurter API 会使用缓存数据，因此启动速度应该更快，但仍会获取最新汇率。

FRANKFURTER_API_URL=http://frankfurter_api:8080/v1 docker compose --profile local_api up --build frankfurtermcp frankfurter_api

要停止使用 local_api 配置文件创建的容器组，请运行以下命令。

docker compose --profile local_api down

docker-compose.yml 文件包含安全加固措施，包括只读文件系统（适用时）、移除功能以及资源限制。

注意：本地 API 服务使用 Frankfurter GitHub 仓库中的最新代码构建，因此可能不稳定。如果要使用特定提交，请将 docker-compose.yml 文件中 frankfurter_api_base 下 build 的 context 字段改为指向特定提交哈希，例如，使用提交 0b6dbd80716f5abe27e8759fc548b74d35fa82b9：https://github.com/lineofflight/frankfurter.git#0b6dbd80716f5abe27e8759fc548b74d35fa82b9。

成功构建并启动容器后，MCP 服务将通过 HTTP 提供访问：使用 Server Sent Events（SSE）传输时，地址为 http://localhost:8000/sse；使用可流式 HTTP 传输时，地址为 http://localhost:8000/mcp。如果还启动了本地 Frankfurter API 服务，API 端点地址为 http://localhost:8080/v1。

云托管服务

当前可用的云托管选项如下。

• FastMCP Cloud：https://frankfurtermcp.fastmcp.app/mcp
• Glama.AI：https://glama.ai/mcp/servers/@anirbanbasu/frankfurtermcp

客户端访问

本小节介绍客户端连接并测试 FrankfurterMCP 服务的方式。

官方 MCP 可视化检查器

MCP Inspector 是一款 官方 的 Model Context Protocol 工具，开发者可用它测试和调试 MCP 服务。这是探索 MCP 服务最全面的方式。

要使用它，必须安装 Node.js。安装和管理 node 以及 MCP Inspector 等软件包的最佳方式是使用 Node Version Manager（或 nvm）。安装 nvm 后，可以执行以下命令安装并使用最新的长期支持版本 node。

nvm install --lts
nvm use --lts

随后，在 WD 中执行以下命令来（安装并）运行 MCP Inspector。

npx @modelcontextprotocol/inspector uv run frankfurtermcp

这会在端口 6274 上创建一个带有身份验证令牌的本地 URL，你可以复制该 URL 并在浏览器中访问。进入 MCP Inspector UI 后，按下 Connect 以连接到 MCP 服务。之后，你可以探索服务提供的工具。

Claude Desktop、Visual Studio 等

以下是使用 stdio 传输方式运行服务的条目，可用于 Claude Desktop、Visual Studio Code 等系统。

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

或者，使用 uvx：

{
    "command": "uvx",
    "args": [
        "frankfurtermcp"
    ]
}

你可能需要将 args 列表中的最后一项 frankfurtermcp 替换为脚本的完整路径，例如 WD/.venv/bin/frankfurtermcp。同样，也可以不使用 uv，而采用以下 JSON 配置，并将 python3.12 替换为正确的路径，例如 WD/.venv/bin/python3.12。

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

可用 MCP 功能列表

FrankfurterMCP 提供以下 MCP 功能。

工具

下表列出了 FrankfurterMCP 服务公开的工具名称。此处显示的描述仅供文档参考，可能与通过 model context protocol 公开的实际描述不同。

名称	描述
get_supported_currencies	获取 Frankfurter API 支持的货币列表。
get_latest_exchange_rates	获取指定基础货币在特定货币中的最新汇率。
convert_currency_latest	使用最新汇率将金额从一种货币兑换为另一种货币。
get_historical_exchange_rates	获取指定基础货币在特定货币中的某个日期或日期范围的历史汇率。
convert_currency_specific_date	使用指定日期的汇率将金额从一种货币兑换为另一种货币。
greet	获取 FrankfurterMCP 服务的问候语。此工具主要用于内部测试。

为简洁起见，下表未列出各工具的必需参数和可选参数，但 MCP 客户端可以通过协议获取这些参数。

贡献

安装 prek。然后在 WD 中运行以下命令以启用 prek。

prek install

欢迎提交拉取请求。对于重大更改，请先创建 issue，讨论你希望进行的更改。

测试与覆盖率

运行以下命令即可执行提供的测试用例。向命令添加 --capture=tee-sys 标志可显示更多控制台输出。

uv run --group test pytest tests/

执行 just test-coverage 以运行所有测试并生成覆盖率报告，如下所示。如果运行了所有测试，生成的覆盖率报告可能如下所示。

---------------------------------------------------------------------------------------- benchmark: 2 tests ---------------------------------------------------------------------------------------
Name (time in ms)                         Min               Max              Mean            StdDev            Median               IQR            Outliers       OPS            Rounds  Iterations
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
test_get_historical_exchange_rates     4.4944 (1.0)      5.1512 (1.0)      4.7919 (1.0)      0.2460 (1.0)      4.7819 (1.0)      0.3249 (1.0)           2;0  208.6840 (1.0)           5           1
test_get_latest_exchange_rates         4.7937 (1.07)     5.6976 (1.11)     5.3257 (1.11)     0.3345 (1.36)     5.4182 (1.13)     0.3575 (1.10)          2;0  187.7702 (0.90)          5           1
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

Legend:
  Outliers: 1 Standard Deviation from Mean; 1.5 IQR (InterQuartile Range) from 1st Quartile and 3rd Quartile.
  OPS: Operations Per Second, computed as 1 / Mean
=============================================================== 15 passed in 4.09s ===============================================================
Name    Stmts   Miss    Cover   Missing
---------------------------------------
TOTAL     265      0  100.00%

6 files skipped due to complete coverage.
Test coverage complete.

许可证

MIT。

安全注意事项

本节记录漏洞扫描中发现的安全相关问题，并为部署决策提供背景信息。

Airtable 漏洞扫描结果与说明

请查看下方 Airtable 漏洞扫描（搜索 frankfurtermcp）中的安全相关结果，以及相应的说明和反驳意见。

规则 ID	问题与反驳意见
MCP-R001	问题：服务器启动时动态注册工具，但没有加密签名、不可变版本控制或完整性检查。该架构允许热重载场景（通过 register_features 模式），但不存在签名验证或审批流程。 反驳意见：工具并非从外部来源或插件加载，而是直接定义在应用程序源代码中。通过版本控制和代码审查流程确保完整性。由于工具属于应用程序二进制文件的一部分（而非动态加载的插件），加密签名只会增加复杂性，不会带来实质性的安全收益。
MCP-R004	问题：服务器会发出警告，但仍接受 CORS 来源中的通配符。 反驳意见：使用 HTTP 传输时，本服务器并非设计为可直接在生产环境中运行。对于需要更严格控制 CORS 来源的部署，用户应使用 .env.template 默认值（127.0.0.1），并将服务器部署在自己的反向代理后面，在反向代理层配置适当的 CORS 来源控制。
MCP-R013	问题：当服务器绑定到 127.0.0.1 以外的任何 IP 地址时，不支持 HTTPS。 反驳意见：使用 HTTP 传输时，本服务器并非设计为可直接在生产环境中运行并支持 HTTPS。对于需要支持 HTTPS 的部署，用户应使用 .env.template 默认值（127.0.0.1），并将服务器部署在自己的反向代理后面，配置适当的 HTTPS。
MCP-R018	问题：没有身份验证或授权检查。 反驳意见：使用 HTTP 传输时，本服务器并非设计为直接以多用户模式运行。对于需要访问控制的部署，用户应使用 .env.template 默认值（127.0.0.1），并将服务器部署在自己的反向代理后面，配置适当的安全控制。

项目状态

截至本 README 最近一次更新，项目当前状态为活跃。有关变更的详细列表，请参阅 CHANGELOG。