Firefly III MCP Server

通过 Model Context Protocol，让 AI 助手能够读取——如果你允许，还可以写入——你自己的 Firefly III 实例。

涵盖 26 个实体、146 项操作：交易、账户、预算、类别、标签、账单、存钱罐、规则，以及搜索和期间分析。

Türkçe: README.tr.md

每个人都是使用自己的 Firefly 实例和自己的令牌来运行它。不会共享任何内容，也没有数据经过第三方。

安装

需要 Node.js 20.6+。最快的方式是让安装程序来完成：

npx -y @yakupemreyerli/firefly-mcp setup

它会询问你的 Firefly III 地址和 API 令牌，检查它们是否真的能在你的实例上工作，然后如果发现 Claude Code 和 Claude Desktop，就会配置它们——备份它所触及的任何内容，并且不碰你的其他 MCP 服务器。对于任何其他客户端，它会打印出可供粘贴的配置。

如果你更愿意手动操作：

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"
      }
    }
  }
}

从 Firefly III 获取令牌：选项 → 个人资料 → OAuth → 创建新的个人访问令牌。对于 URL，你的域名就足够了——https:// 和 /api/v1 会自动补全。如果你的实例位于子路径、自定义端口或纯 http 之后，请提供完整的 URL。

Related MCP server: Firefly III MCP Server

它能走多远

通过 stdio，权限范围由 Firefly 令牌决定：你可以让助手记录一笔购买或对交易进行分类，它会照做。没有服务器级的权限设置——对于只能回答问题的会话，请在 Firefly III 中签发一个只读的个人访问令牌，这样限制由 Firefly 强制执行，而不是由同一个人可以编辑的变量来执行。

通过 HTTP 和 OAuth，访问权限按连接决定：firefly:read、firefly:write 和 firefly:destructive 在密码界面授予，未被授予的工具面既会被隐藏，也会被拒绝。

助手能看到什么

五个工具，而不是 146 个——并且执行按风险拆分，因此主机可以区分读取余额和删除交易：

每个工具都带有 MCP 工具注解（readOnlyHint、destructiveHint、idempotentHint），并且这种拆分是强制执行的，而不仅仅是宣传：通过 firefly_query 发起的删除会被拒绝。仅被授予 firefly:read 的连接根本看不到那两个写入工具。

大多数 MCP 客户端在超过大约 40 个工具后会降级，这就是为什么工具面只有三个。

响应在到达模型之前会被裁剪：空值和 null 属性总是被丢弃，每个执行工具都接受一个 fields 列表，只保留你指定的属性——对于大型交易列表，这大约能减少 90% 的数据。

配置

远程 HTTP 模式

对于通过 HTTP 连接而不是启动进程的客户端——例如 n8n——同一个服务器支持流式 HTTP：

export MCP_HTTP_TOKEN=$(openssl rand -hex 32)
npx -y -p @yakupemreyerli/firefly-mcp firefly-mcp-http

firefly-mcp-http 是同一个包中的第二个二进制文件，这就是为什么 npx 需要 -p 来分别指定包名和命令。

没有 MCP_HTTP_TOKEN 它拒绝启动，并且对 /mcp 的每个请求都必须携带 Authorization: Bearer <token>。/health 是开放的，用于容器探针。Dockerfile 和 compose.example.yml 位于仓库中。

请将它放在 TLS 之后。令牌是互联网与你的财务历史写入权限之间的唯一屏障——不要直接暴露端口。

文档

Docker

对于 HTTP 模式，有一个预构建的镜像，支持 linux/amd64 和 linux/arm64：

docker run -d \
  -e FIREFLY_API_URL=your-firefly.example \
  -e FIREFLY_API_TOKEN=your-token \
  -e MCP_HTTP_HOST=0.0.0.0 \
  -e MCP_HTTP_TOKEN="$(openssl rand -hex 32)" \
  -p 3000:3000 \
  ghcr.io/yakupemreyerli/mcp-firefly-iii:latest

/health 无需令牌即可响应，用于容器探针。/mcp 上的所有内容都需要 Authorization: Bearer <MCP_HTTP_TOKEN>。

对于任何你依赖的东西，请固定版本（:0.3.1），而不是使用 :latest。

开发

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 中的实例遍历每个读取操作；它是只读的，不属于已发布包的一部分。

贡献

欢迎提交错误报告和拉取请求。请参阅 CONTRIBUTING.md 了解代码布局、如何运行测试，以及在动手之前值得了解的 Firefly III 怪癖。

发现安全问题？请私下报告——参见 SECURITY.md。

许可证

MIT——参见 LICENSE。