Firefly Iii (mcp-server-firefly-iii)

通用萤火虫III AI桥（v3.0.0）

专业级人工智能诊断桥，提供100%API覆盖范围，将人工智能助手连接到您的 萤火虫III 个人理财实例。

66工具 涵盖Firefly III的所有主要功能：账户、交易、预算、账单、重复规则、自动化、洞察、附件、货币等。

______________________________________________________________________

兼容性

______________________________________________________________________

安装

先决条件

• v18或更高版本
• 跑步 萤火虫III 例子
• A. 个人访问令牌 萤火虫III\

*（个人资料→ OAuth→ 个人访问令牌→ 创建新令牌）*

克隆并安装

git clone https://github.com/fabianonetto/mcp-server-firefly-iii.git
cd mcp-server-firefly-iii
npm install

______________________________________________________________________

按平台设置

克劳德代码（推荐）

克劳德代码使用 .mcp.json 在MCP服务器配置的项目目录中。凭证单独存放 .env 这样配置文件中就不会有任何秘密。

1.创建 .env 在repo根目录中（gitignored-never committed）：

FIREFLY_URL=http://your-host:PORT
FIREFLY_TOKEN=your_personal_access_token

获取您的代币：萤火虫III→ 简介→ OAuth→ 个人访问令牌→ 创建新令牌

2.创建 .mcp.json 在repo根目录中（gitignored-never committed）：

{
  "mcpServers": {
    "firefly-iii": {
      "command": "node",
      "args": ["./index.js"]
    }
  }
}

服务器从以下位置读取凭据 .env 自动。没有秘密 .mcp.json.

3.启动克劳德代码 从repo目录：

claude

服务器自动启动。Claude Code将在首次启动时提示您批准它（仅一次）。

4.验证 通过询问以下问题来建立联系：

Use the get_about tool

您应该收到您的Firefly III版本和API信息。

从其他项目中使用：\ 复制两者 .env 和 .mcp.json 更改到任何其他项目目录 ./index.js 到绝对路径：

"args": ["/absolute/path/to/mcp-server-firefly-iii/index.js"]

看 CLAUDE.md 了解包括自动审批配置在内的完整指南。

______________________________________________________________________

克劳德桌面版

将服务器添加到Claude Desktop配置文件中：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• 视窗: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "firefly-iii": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server-firefly-iii/index.js"],
      "env": {
        "FIREFLY_URL": "http://your-host:PORT",
        "FIREFLY_TOKEN": "your_personal_access_token"
      }
    }
  }
}

保存后重新启动Claude Desktop。

______________________________________________________________________

Gemini CLI扩展（一个命令安装）

gemini extensions install https://github.com/fabianonetto/mcp-server-firefly-iii

然后配置您的实例：

gemini config set extensions.firefly-iii-universal-bridge.settings.FIREFLY_URL "http://your-host:PORT"
gemini config set extensions.firefly-iii-universal-bridge.settings.FIREFLY_TOKEN "your_token"

看 gemini.md 完整的指南。

______________________________________________________________________

Docker（官方图片）

官方图片可在GitHub Packages上找到： ghcr.io/fabianonetto/mcp-server-firefly-iii.

作为服务运行（SSE模式）

非常适合ChatGPT操作、游标（SSE）或自定义集成。

docker run -d \
  --name firefly-mcp \
  -p 3001:3001 \
  -e FIREFLY_URL="http://your-firefly-instance" \
  -e FIREFLY_TOKEN="your_personal_access_token" \
  -e PORT=3001 \
  ghcr.io/fabianonetto/mcp-server-firefly-iii:latest

使用克劳德桌面运行（stdio模式）

将此添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "firefly-iii": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "FIREFLY_URL=http://your-host:PORT",
        "-e", "FIREFLY_TOKEN=your_token",
        "ghcr.io/fabianonetto/mcp-server-firefly-iii:latest"
      ]
    }
  }
}

______________________________________________________________________

光标/VS代码（MCP扩展）

添加到MCP配置(.cursor/mcp.json 或同等）：

{
  "mcpServers": {
    "firefly-iii": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server-firefly-iii/index.js"],
      "env": {
        "FIREFLY_URL": "http://your-host:PORT",
        "FIREFLY_TOKEN": "your_personal_access_token"
      }
    }
  }
}

______________________________________________________________________

HTTP/SSE模式（ChatGPT操作、自定义应用程序）

使用端口启动服务器以启用REST和SSE端点：

FIREFLY_URL=http://your-host:PORT FIREFLY_TOKEN=your_token PORT=3000 node index.js

可用端点：

______________________________________________________________________

工具类别

______________________________________________________________________

文档

______________________________________________________________________

运行测试

npm test

78个测试，涵盖所有66个工具。不需要Firefly III实例-所有API调用都被嘲笑。 看 docs/TEST.md 了解详情。

______________________________________________________________________

安全

• 如果将服务器暴露在互联网上，请使用VPN或SSH隧道。
• 保持你的 FIREFLY_TOKEN 秘密。永不承诺 .mcp.json 或 .env 文件夹。
• 看 安全.md 完整的安全策略。

______________________________________________________________________

路线图

• \[x\] v1.x——初始连接
• \[x\] v2.x-详尽的API覆盖范围（CRUD和核心管理员）
• \[x\] v3.x——高级用户功能（拆分、洞察、自动化）
• \[x\] v3.1.0--官方Docker镜像和CI/CD