Firefly III MCP Server

Firefly III MCP サーバー

これは、無料でオープンソースの個人向け家計管理ツールである 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 ベースのサーバー実装

機能

• AI を介して Firefly III インスタンスと連携
• アカウントと取引をプログラムから管理
• さまざまな財務処理に対応する拡張可能なツールセット
• ローカルとクラウドの両方へのデプロイに対応
• Model Context Protocol 標準に準拠
• プリセットまたはカスタムタグによるツールのフィルタリングでトークン使用量を削減

前提条件

• 稼働中の Firefly III インスタンス
• 「Deploy to Cloudflare」ボタンを使ってデプロイする場合は、Cloudflare アカウント

はじめに

1. Firefly III の Personal Access Token（PAT）を取得する

MCP サーバーが Firefly III インスタンスと連携できるようにするには、Personal Access Token（PAT）を生成する必要があります。

1. Firefly III インスタンスにログインします
2. Options > Profile > OAuth に移動します
3. 「Personal access tokens」セクションで、「Create new token」をクリックします
4. トークンにわかりやすい名前を付けます（例：「MCP Server Token」）
5. 「Create」をクリックします
6. 重要： 生成されたトークンをすぐにコピーしてください。後から再表示することはできません。

詳しくは、Firefly III の公式ドキュメント「Personal Access Tokens」を参照してください。

2. MCP サーバーを設定する

Firefly III の PAT と Firefly III インスタンスの URL を MCP サーバーに渡す必要があります。いくつかの方法があります。

リクエストヘッダー（推奨）

各 MCP サーバーリクエストのヘッダーにこれらの値を指定します。一般に、これが最も安全な方法です。

• X-Firefly-III-Url：Firefly III インスタンスの URL（例：https://firefly.yourdomain.com）
• Authorization：Personal Access Token。通常は Bearer を先頭に付けます（例：Bearer YOUR_FIREFLY_III_PAT）

想定される正確なヘッダー名については、使用する AI ツールまたはクライアントのドキュメントを確認してください。

クエリパラメーター（注意して使用）

代わりに、各 MCP サーバーリクエストのクエリパラメーターにこれらの値を指定することもできます。

• baseUrl：Firefly III インスタンスの URL
• pat：Firefly III の Personal Access Token

クエリパラメーターを含む 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：ローカルモード

この方法は、Claude Desktop など、標準入出力（stdio）経由で MCP ツールを呼び出せるクライアントに適しています。

基本的な実行コマンド：

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