mcp-firefly-iii

Firefly III MCP 服务

一个 Model Context Protocol 服务，让 AI 助手能够访问你自己的 Firefly III 实例——通过 5 个权限范围明确的工具提供 152 项操作，并将读取、写入和删除分别放在三个独立且需明确授权的操作入口中，而不是交给一个可以包办三者的工具。

土耳其语：README.tr.md

• “我上个月最大的一笔支出是什么？”
• “找出 8 月份未分类的交易，并建议分类。”
• “显示金额上涨的订阅。”

每个人都使用自己的令牌，将此服务连接到自己的 Firefly 实例——中间没有托管后端或中继服务。

该项目已收录于官方 MCP Registry，标识为 io.github.YakupEmreYerli/mcp-firefly-iii，也收录于 Glama，以及 Firefly III 自己的第三方应用文档中。每个版本均由 CI 从带标签的提交构建并发布，并通过 npm provenance证明软件包归档来自此代码库。

演示

https://github.com/user-attachments/assets/4866f13e-ff09-43b0-b99c-2b4789a30224

38 秒演示：提出一个财务问题，通过 MCP 读取答案，使用 dry_run 预览更改，批准后将更改写回 Firefly III。演示基于合成实例录制——展示的所有财务数据均为虚构。

功能

• 5 个元工具，而非 152 个。 firefly_query、firefly_mutate、firefly_destructive，以及用于发现的 firefly_list_operations 和 firefly_get_schema——一个类型化注册表将每个 Firefly 端点映射到这些工具中，避免工具列表塞满模型。
• 每次写入都支持 dry_run，会返回确切的请求——包括已解析的记录 ID——但不会发送请求。
• 批量写入不能盲目执行。 由筛选条件驱动的更新必须指定 max_matches，并且在首次写入前会因扫描不完整而拒绝执行；多拆分交易组则会被直接拒绝，以免将各笔金额错误地合并。
• 读取、写入和破坏性操作分别限定权限并强制执行，而不只是标注——stdio 连接通过 Firefly 令牌控制，HTTP 连接则通过 OAuth 权限范围或静态令牌控制。
• 内置 OAuth 2.1 授权服务器，支持 Claude 网页版、Claude 移动端和 ChatGPT——无需单独安装 Keycloak 或 Authentik。
• 提供适用于 linux/amd64 和 linux/arm64 的 Docker 镜像，并配有自检式文档流程，确保工具目录与代码保持同步。
• 版本过期时会提醒你。 它每天检查一次是否有新版本；如果有，只会提醒一次——在 stderr 上输出一行，并在下一次回答旁附上一句话。设置 MCP_UPDATE_CHECK=false 可关闭此功能。

前置条件

• 正在运行的 Firefly III 实例和个人访问令牌（Firefly III → 选项 → 个人资料 → OAuth → 创建新的个人访问令牌）
• Node.js 20.6+，除非你使用 Docker

用法

方法	传输方式	适用场景
npx — stdio	stdio	Claude Code、Claude Desktop、Cursor — 最简单的设置方式
静态令牌	HTTP	n8n、自动化、无头调用方
OAuth	HTTP + OAuth	Claude 网页版、Claude 移动版、ChatGPT — 无法保存静态令牌
Docker	HTTP	可自托管，可使用上述任一种身份验证方式

1. stdio（Claude Code、Claude Desktop、Cursor）

让设置程序来完成 — 它会询问你的 Firefly III 地址和令牌，验证它们是否有效，然后在检测到 Claude Code 和 Claude Desktop 时为其配置。运行 npx -y @yakupemreyerli/firefly-mcp setup 即可。对于其他客户端，它会输出需要粘贴的配置。

手动配置 Claude Code：

claude mcp add firefly --env FIREFLY_API_URL=your-firefly.example --env FIREFLY_API_TOKEN=your-token -- npx -y @yakupemreyerli/firefly-mcp

手动配置 Claude Desktop / Cursor / 其他客户端 — 将以下内容添加到 MCP 配置文件：

{
  "mcpServers": {
    "firefly": {
      "command": "npx",
      "args": ["-y", "@yakupemreyerli/firefly-mcp"],
      "env": { "FIREFLY_API_URL": "your-firefly.example", "FIREFLY_API_TOKEN": "your-token" }
    }
  }
}

2. 使用静态令牌的远程 HTTP

适用于 n8n、自动化，或任何无法执行基于浏览器的 OAuth 流程的调用方。在 .env 中设置 MCP_HTTP_TOKEN，然后运行 npx -y -p @yakupemreyerli/firefly-mcp firefly-mcp-http。每个发送到 /mcp 的请求都必须携带 Authorization: Bearer <token> — 一个令牌即可完全访问，且不按连接范围进行限制。

3. 使用 OAuth 的远程 HTTP（Claude 网页版、Claude 移动版、ChatGPT）

这些客户端都无法保存静态令牌，也无法启动本地进程 — 它们会连接到公开的 HTTPS URL，并要求使用 OAuth。设置 MCP_AUTH_PASSWORD 后，此服务就是 OAuth 2.1 授权服务器：它会自行处理客户端注册、PKCE 和令牌交换，因此无需 Keycloak、无需 Google 登录，也无需在任何地方复制令牌。

步骤 1 — 为服务提供公开的 HTTPS 地址。 对于家用服务器，Cloudflare Tunnel 是最简单的方案（无需端口转发，也无需证书）；在 VPS 上则可以使用 Caddy 或 Traefik。compose.example.yml 提供了专用的 cloudflare 和 caddy 配置文件。假设最终地址为 https://mcp.example.com。

步骤 2 — 配置 .env：

MCP_AUTH_PASSWORD=a-strong-password-of-at-least-12-characters
MCP_RESOURCE_URL=https://mcp.example.com
MCP_AUTH_STATE_DIR=/data/firefly-mcp-auth

MCP_RESOURCE_URL 必须是外部源地址，字符必须完全一致，且不能包含路径 — 不能使用内部地址 http://firefly-mcp:3000，也不能使用 /mcp 连接 URL。若不匹配，令牌受众检查会失败，客户端只会报告“invalid token”。MCP_AUTH_STATE_DIR 必须位于持久化卷上（compose.example.yml 会挂载一个卷），否则每次重启都会使所有客户端失去授权。

步骤 3 — 启动并验证：

docker compose -f compose.example.yml up -d
curl https://mcp.example.com/health     # {"ok":true,"auth":"oauth-builtin"}

如果 auth 显示的是 bearer，则说明密码没有传递给进程，客户端会报告该服务不支持 OAuth。

步骤 4a — Claude（网页版、Desktop、iOS/Android）。 Settings → Connectors → Add custom connector，URL 填写 https://mcp.example.com/mcp。保留自动检测到的身份验证选项 — Claude 会探测服务并选择其支持的流程。此后，该连接器可在你已登录的所有 Claude 平台上使用，包括手机。

步骤 4b — ChatGPT。 在自定义连接器 / MCP 页面中，输入同一个 https://mcp.example.com/mcp，并选择 OAuth 作为身份验证方式。

步骤 5 — 输入密码。 浏览器中会打开 Firefly 登录页面；输入 MCP_AUTH_PASSWORD。这个页面就是唯一的授权环节 — 无论客户端本身请求了哪些范围，连接都会获得全部三个范围（firefly:read、firefly:write、firefly:destructive）。不会出现第二个授权确认页面：持有密码的人本可以勾选其中所有选项。若要提供确实无法写入的连接，请改为向服务提供只读的 Firefly Personal Access Token。

完整的 TLS 配置指南和故障排查：docs/oauth.md。

4. Docker

建议用于上述任一种 HTTP 模式：

cp .env.example .env    # fill in the values for the mode you need
docker compose -f compose.example.yml up -d

将 compose.example.yml 中的 build: . 替换为 image: ghcr.io/yakupemreyerli/mcp-firefly-iii:latest，即可使用预构建镜像；对于任何依赖项，请固定版本标签，不要使用 :latest。不使用 Compose 运行单个容器：docker run -d --env-file .env -p 3000:3000 ghcr.io/yakupemreyerli/mcp-firefly-iii:latest。如果未启用上述两种身份验证模式之一，服务将拒绝启动；/mcp 前面需要有 TLS，compose.example.yml 为此提供了可选的 cloudflare 和 caddy 配置档。/health 无需身份验证，可用于容器探测。

配置

变量	默认值	用途
FIREFLY_API_URL	—	必填。裸域名，或包含 /api/v1 的完整基础 URL。
FIREFLY_API_TOKEN	—	必填。个人访问令牌。
FIREFLY_DISABLE_SSL_VERIFY	false	仅用于使用自签名证书的本地实例。
MCP_UPDATE_CHECK	true	每日检查是否有更新版本。这是此服务向 Firefly 实例以外的任何位置发送的唯一请求，且不携带任何数据。

所有变量（包括 HTTP 和 OAuth 模式）：docs/configuration.md。

工具

工具	可回答的问题	风险
firefly_query	查询任何内容。其描述包含操作目录，因此选择操作无需额外调用。	只读
firefly_mutate	创建或更改记录。	写入
firefly_destructive	删除记录，或一次性重写多条记录中的同一字段。	无法撤销
firefly_list_operations	我可以对这个实体执行哪些操作？	只读
firefly_get_schema	此操作需要哪些参数？	只读

这种划分由系统强制执行，而非仅作声明——通过 firefly_query 执行的删除请求会被拒绝；仅获得 firefly:read 权限的连接甚至看不到两个写入工具。响应会在到达模型前进行精简：始终移除空值和 null 属性，每个执行工具都接受 fields 列表——对于大型交易列表，数据量大约可减少 90%。完整参考：docs/api/operations.md。

安全

此服务绝不会将你的数据发送给第三方，但对于你连接的 AI 客户端或模型在收到响应后如何处理它，服务无法控制。完整威胁模型：SECURITY.md。发现漏洞？请通过该页面私下报告。

文档

页面	内容
快速入门	获取令牌、配置客户端、首次尝试和故障排除
配置	所有环境变量、权限策略、HTTP 模式
通过内置 OAuth 远程访问	为 Claude 网页版、Claude 移动版和 ChatGPT 部署
MCP 集成	Claude Code、Claude Desktop、Cursor、VS Code、n8n 和远程 HTTP
操作	全部 152 项操作、响应精简，以及 Firefly 中容易踩坑的地方
分析操作	summary.overview、搜索和 8 个洞察端点
MCP Inspector	开发期间以交互方式试用服务

开发

git clone https://github.com/YakupEmreYerli/mcp-firefly-iii.git && cd mcp-firefly-iii
npm install
cp .env.example .env    # fill in your instance
npm test                # mocked; never touches a live instance
npm run build
npm run check           # read-only connection check against .env

测试均使用模拟数据，不会访问网络。npm run smoke:live 是维护者工具，会针对 .env 中的实例遍历所有读取操作；它仅执行读取操作，不属于已发布的软件包。欢迎提交 Bug 报告和拉取请求——请参阅 CONTRIBUTING.md。

许可证

MIT——请参阅 LICENSE。

横幅和 docs/assets/ 中的火焰与存钱罐徽标是 Firefly III 自有徽标，不受本许可证涵盖。按照其徽标指南的规定，本项目使用该徽标来指代 Firefly III；Firefly III 并未制作或认可本项目。