Firefly III MCP Server

这是一个面向 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

Related MCP server: Firefly III MCP Server

功能

• 通过 AI 与 Firefly III 实例交互

• 以编程方式管理账户和交易

• 可扩展的工具集，支持多种财务操作

• 支持本地和云端部署

• 兼容模型上下文协议（MCP）标准

• 通过预设或自定义标签过滤工具，减少 token 用量

前置要求

• 一个正在运行的 Firefly III 实例

• 如果您计划使用“Deploy to Cloudflare”按钮进行部署，则需要一个 Cloudflare 账户

快速开始

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

为了让 MCP 服务器与您的 Firefly III 实例交互，您需要生成一个个人访问令牌（PAT）：

1. 登录您的 Firefly III 实例

2. 导航到 选项 > 个人资料 > OAuth

3. 在“Personal access tokens”部分，点击“Create new token”

4. 为您的令牌设置一个描述性名称（例如“MCP Server Token”）

5. 点击“Create”

6. 重要提示： 请立即复制生成的令牌，之后您将无法再次查看。

更多详情，请参阅 Firefly III 官方文档中的 Personal Access Tokens。

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：从源码在本地运行

[!NOTE] 对于生产环境，建议使用 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 客户端暴露的工具来减少 token 用量并专注于特定功能：

可用预设

• default：日常使用的基础工具（账户、账单、类别、标签、交易、搜索、摘要）

• full：全部可用工具

• basic：核心财务管理工具

• budget：专注预算的工具

• reporting：报告和分析工具

• admin：管理工具

• automation：自动化相关工具

开发指南

本项目使用 Turborepo 管理 monorepo 工作流，并使用 Changesets 进行版本管理与发布。

常用命令

• 构建所有包：npm run build

• 构建指定包：npm run build:core 或 npm run build:local

• 清理构建产物：npm run clean

• 开发模式：npm run dev

• 发布包：npm run publish-packages

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

致谢

本项目使用并修改了 harsha-iiiv 的生成脚本。非常感谢原作者的工作。

贡献

欢迎贡献！本项目使用 Turborepo 管理 monorepo 工作流。请参阅 CONTRIBUTING.md 获取详细的贡献指南。

许可证

本项目基于 MIT License 许可证授权。