Firefly III MCP Server

これは、無料のオープンソース個人財務管理ソフトウェアである Firefly III 用の Model Context Protocol（MCP）サーバーです。この MCP サーバーを通じて、ユーザーは AI ツールを活用して Firefly III のアカウントや取引を管理し、個人財務・会計向けの AI アシスタントを作成できます。

中国語版を見る

プロジェクト構成

このプロジェクトは Turborepo で管理されるモノレポ構成を採用しており、以下の主要パッケージが含まれています。

• @firefly-iii-mcp/core - Firefly III API とやり取りするための基盤を提供するコア機能モジュール

• @firefly-iii-mcp/local - MCP サーバーをローカルで実行するためのコマンドラインツール

• @firefly-iii-mcp/cloudflare-worker - Cloudflare Workers へのデプロイ用実装

• @firefly-iii-mcp/server - Streamable HTTP と SSE をサポートする Express ベースのサーバー実装

Related MCP server: Firefly III MCP Server

機能

• AI を介して Firefly III インスタンスを操作できる

• アカウントと取引をプログラムから管理できる

• さまざまな財務操作に対応した拡張可能なツールセット

• ローカルとクラウドの両方でデプロイ可能

• Model Context Protocol 標準に準拠

• プリセットやカスタムタグによるツールのフィルタリングでトークン使用量を削減

前提条件

• 稼働中の 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

利用可能なツールをフィルタリングしてトークン使用量を減らすこともできます:

# 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 アプリに推奨）

この方法では、Streamable HTTP と SSE をサポートする HTTP ベースのサーバーを提供するため、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 と FIRELY_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 クライアントに公開するツールをフィルタリングすることで、トークン使用量を減らし、特定の機能に絞り込むことができます。

利用可能なプリセット

• 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 の下でライセンスされています。