Firefly III MCP Server

Firefly III MCP 服务

这是一个面向 Firefly III 的模型上下文协议（MCP）服务。Firefly III 是一款免费开源的个人财务管理工具。借助此 MCP 服务，用户可以使用 AI 工具管理 Firefly III 账户和交易，打造用于个人财务管理与会计核算的 AI 助手。

查看中文版

项目结构

本项目采用由 Turborepo 管理的 monorepo 结构，包含以下主要软件包：

• @firefly-iii-mcp/core - 核心功能模块，为与 Firefly III API 交互提供基础支持
• @firefly-iii-mcp/local - 用于在本地运行 MCP 服务的命令行工具
• @firefly-iii-mcp/cloudflare-worker - 部署到 Cloudflare Workers 的实现
• @firefly-iii-mcp/server - 基于 Express 的服务实现，支持 Streamable HTTP 和 SSE

功能

• 通过 AI 与 Firefly III 实例交互
• 以编程方式管理账户和交易
• 可扩展的工具集，支持各种财务操作
• 支持本地和云端部署
• 兼容模型上下文协议标准
• 通过预设或自定义标签筛选工具，以减少 token 用量

前提条件

• 正在运行的 Firefly III 实例
• 如果计划使用“部署到 Cloudflare”按钮进行部署，则需要 Cloudflare 账户

入门指南

1. 获取 Firefly III 个人访问令牌（PAT）

若要让 MCP 服务与 Firefly III 实例交互，需要生成个人访问令牌（PAT）：

1. 登录 Firefly III 实例
2. 前往 选项 > 个人资料 > OAuth
3. 在“个人访问令牌”部分，点击“创建新令牌”
4. 为令牌设置一个描述性名称（例如，“MCP 服务令牌”）
5. 点击“创建”
6. **重要：**立即复制生成的令牌。之后将无法再次查看。

更多详情请参阅 Firefly III 官方文档中的个人访问令牌。

2. 配置 MCP 服务

需要向 MCP 服务提供 Firefly III PAT 和 Firefly III 实例 URL。可以通过以下几种方式提供：

请求标头（推荐）

在发往 MCP 服务的每个请求标头中提供这些值。这通常是最安全的方式：

• X-Firefly-III-Url：Firefly III 实例 URL（例如，https://firefly.yourdomain.com）
• Authorization：个人访问令牌，通常以 Bearer 为前缀（例如，Bearer YOUR_FIREFLY_III_PAT）

有关所用 AI 工具或客户端所需标头名称的具体信息，请查阅其文档。

查询参数（谨慎使用）

也可以在发往 MCP 服务的每个请求的查询参数中提供这些值：

• baseUrl：Firefly III 实例 URL
• pat：Firefly III 个人访问令牌

请注意，URL（包括查询参数）可能会在多个位置被记录，从而导致敏感信息泄露。

环境变量（主要用于自托管／本地开发）

运行服务前设置以下环境变量：

FIREFLY_III_BASE_URL="YOUR_FIREFLY_III_INSTANCE_URL" # e.g., https://firefly.yourdomain.com
FIREFLY_III_PAT="YOUR_FIREFLY_III_PAT"
# Optional: Filter tools using preset or custom tags
FIREFLY_III_PRESET="default" # Available: default, full, basic, budget, reporting, admin, automation
# Or specify custom tool tags (overrides preset if both are set)
FIREFLY_III_TOOLS="accounts,transactions,categories"

运行 MCP 服务

方法 1：本地模式

此方法适用于支持通过标准输入／输出（stdio）调用 MCP 工具的客户端，例如 Claude Desktop。

基本运行命令：

npx @firefly-iii-mcp/local --pat YOUR_PAT --baseUrl YOUR_FIREFLY_III_URL

也可以筛选可用工具，以减少 token 用量：

# Using a preset
npx @firefly-iii-mcp/local --pat YOUR_PAT --baseUrl YOUR_FIREFLY_III_URL --preset budget

# Using custom tool tags
npx @firefly-iii-mcp/local --pat YOUR_PAT --baseUrl YOUR_FIREFLY_III_URL --tools accounts,transactions,categories

也可以参阅官方教程，了解如何使用 JSON 格式进行配置。

{
  "mcpServers": {
    "firefly-iii": {
      "command": "npx",
      "args": [
        "@firefly-iii-mcp/local",
        "--pat",
        "<Your Firefly III Personal Access Token>",
        "--baseUrl",
        "<Your Firefly III Base URL>",
        "--preset",
        "default"
      ]
    }
  }
}

方法 2：Express 服务（推荐用于 Web 应用）

此方法提供基于 HTTP 的服务，支持 Streamable HTTP 和 SSE，非常适合 Web 应用。

作为命令行工具

npx @firefly-iii-mcp/server --pat YOUR_PAT --baseUrl YOUR_FIREFLY_III_URL

命令行选项：

• -p, --pat <token> - Firefly III 个人访问令牌
• -b, --baseUrl <url> - Firefly III 基础 URL
• -P, --port <number> - 要监听的端口（默认：3000）
• -l, --logLevel <level> - 日志级别：debug、info、warn、error（默认：info）
• -s, --preset <name> - 要使用的工具预设（default、full、basic、budget、reporting、admin、automation）
• -t, --tools <list> - 要启用的工具标签列表，以逗号分隔

作为库

npm install @firefly-iii-mcp/server

基本用法：

import { createServer } from '@firefly-iii-mcp/server';

const server = createServer({
  port: 3000,
  pat: process.env.FIREFLY_III_PAT,
  baseUrl: process.env.FIREFLY_III_BASE_URL,
  enableToolTags: ['accounts', 'transactions', 'categories'] // Optional: Filter available tools
});

server.start().then(() => {
  console.log('MCP Server is running on http://localhost:3000');
});

详情请参阅 @firefly-iii-mcp/server 文档。

方法 3：部署到 Cloudflare Workers（推荐用于生产环境）

使用下方按钮，即可轻松将此 MCP 服务部署到 Cloudflare Workers：

**注意：**部署后，你需要在 Cloudflare Worker 的设置中配置环境变量：

1. 前往 Cloudflare 控制面板
2. 打开 Workers & Pages
3. 选择已部署的 Worker
4. 前往 Settings > Variables
5. 添加以下变量：
   • 必需：FIREFLY_III_BASE_URL 和 FIREFLY_III_PAT
   • 可选：FIREFLY_III_PRESET 或 FIREFLY_III_TOOLS

方法 4：从源码在本地运行

说明

对于生产环境，建议使用 NPM 包或部署到 Cloudflare Workers。

1. 克隆仓库：

   git clone https://github.com/etnperlong/firefly-iii-mcp.git
   cd firefly-iii-mcp
   

2. 安装依赖：

   npm install
   

3. 创建 .env 文件：

   FIREFLY_III_BASE_URL="YOUR_FIREFLY_III_INSTANCE_URL"
   FIREFLY_III_PAT="YOUR_FIREFLY_III_PAT"
   # Optional: Filter tools
   FIREFLY_III_PRESET="default"
   # Or
   FIREFLY_III_TOOLS="accounts,transactions,categories"
   

4. 构建项目：

   npm run build
   

5. 启动开发服务器：

   npm run dev
   

工具筛选选项

你可以筛选向 MCP 客户端公开的工具，以减少令牌用量并专注于特定功能：

可用预设

• default：适用于日常使用的基础工具（账户、账单、类别、标签、交易、搜索、摘要）
• full：所有可用工具
• basic：核心财务管理工具
• budget：专注于预算的工具
• reporting：报告和分析工具
• admin：管理工具
• automation：与自动化相关的工具

开发指南

此项目使用 Turborepo 管理单仓库工作流，并使用 Changesets 进行版本管理和发布。

常用命令

• 构建所有包：npm run build
• 构建指定包：npm run build:core 或 npm run build:local
• 清理构建产物：npm run clean
• 开发模式：npm run dev
• 发布包：npm run publish-packages

详细的开发指南请参阅贡献指南。

致谢

此项目使用并修改了 harsha-iiiv/openapi-mcp-generator 中的生成脚本。衷心感谢原作者所做的工作。

贡献

欢迎贡献！此项目使用 Turborepo 管理单仓库工作流。有关贡献的详细指南，请参阅 CONTRIBUTING.md。

许可证

此项目采用 MIT License 授权。