mcp-firefly-iii

Firefly III MCP サーバー

AI アシスタントが独自の Firefly III インスタンスにアクセスできる Model Context Protocol サーバーです。読み取り、書き込み、削除を、すべてを実行できる1つのツールにまとめるのではなく、明示的に許可された3つの領域として分け、5つのスコープ付きツールで152の操作を提供します。

Türkçe: README.tr.md

• 「先月、最も多くお金を使ったのは何ですか？」
• 「8月の未分類の取引を探して、カテゴリを提案してください。」
• 「金額が増えたサブスクリプションを見せてください。」

すべてのユーザーが、自分のトークンを使って自分の Firefly インスタンスに接続します。間にホスト型バックエンドやリレーはありません。

公式の MCP Registry では io.github.YakupEmreYerli/mcp-firefly-iii として、Glama ではサーバーとして、また Firefly III 独自のサードパーティアプリのドキュメントにも掲載されています。すべてのリリースは、タグ付きコミットから CI によってビルドおよび公開されます。npm provenanceにより、tarball がこのリポジトリから作成されたことが証明されます。

デモ

https://github.com/user-attachments/assets/4866f13e-ff09-43b0-b99c-2b4789a30224

38秒のデモです。財務に関する質問をして、MCP 経由で回答を読み取り、dry_run で変更をプレビューしてから承認し、Firefly III に書き戻します。合成インスタンスを使って録画しており、表示される財務データはすべて架空のものです。

機能

• 152個ではなく、5つのメタツール。 firefly_query、firefly_mutate、firefly_destructiveに加え、探索用のfirefly_list_operationsとfirefly_get_schemaを用意しています。型付きレジストリがすべての Firefly エンドポイントをこれらに割り当てるため、モデルのツール一覧が膨れ上がりません。
• すべての書き込み操作にdry_runを用意。 解決済みのレコード ID を含む正確なリクエストを返し、送信はしません。
• 一括書き込みを無確認では実行できません。 フィルター駆動の更新にはmax_matchesが必要で、完全なスキャンができない場合は最初の書き込み前に拒否します。複数の分割を含む取引グループは、金額がまとめられるリスクを避けるため、すべて拒否します。
• 読み取り／書き込み／破壊的操作は、それぞれ独立してスコープが設定され、強制されます。 単なる注釈ではなく、stdio では Firefly トークンにより、HTTP では OAuth スコープまたは静的トークンにより制御されます。
• Claude ウェブ、Claude モバイル、ChatGPT 向けの OAuth 2.1 認可サーバーを内蔵。 Keycloak や Authentik を別途インストールする必要はありません。
• linux/amd64／linux/arm64向けの Docker イメージと、ツールカタログをコードと同期させる自己チェック機能付きドキュメントパイプラインを用意しています。
• 古くなったことを通知します。 1日1回、新しいバージョンが存在するかを確認し、存在する場合は一度だけ通知します。stderr に1行表示され、次の回答の横に一文が表示されます。MCP_UPDATE_CHECK=falseで無効にできます。

前提条件

• Firefly III インスタンスが稼働していること、および Personal Access Token（Firefly III → Options → Profile → OAuth → Create New Personal Access Token）
• Docker を使わない場合は Node.js 20.6 以降

使用方法

方法	トランスポート	最適な用途
npx — stdio	stdio	Claude Code、Claude Desktop、Cursor — 最も簡単なセットアップ
静的トークン	HTTP	n8n、自動化、ヘッドレスクライアント
OAuth	HTTP + OAuth	Claude web、Claude mobile、ChatGPT — 静的トークンを保持できないクライアント
Docker	HTTP	セルフホスト。上記いずれかの認証方式を利用

1. stdio（Claude Code、Claude Desktop、Cursor）

セットアップに任せましょう。Firefly III のアドレスとトークンを尋ね、それらが実際に機能することを確認したうえで、Claude Code と Claude Desktop が見つかった場合は設定します。npx -y @yakupemreyerli/firefly-mcp setup を実行してください。それ以外のクライアントの場合は、貼り付け用の設定を表示します。

手動で設定する場合、Claude Code：

claude mcp add firefly --env FIREFLY_API_URL=your-firefly.example --env FIREFLY_API_TOKEN=your-token -- npx -y @yakupemreyerli/firefly-mcp

手動で設定する場合、Claude Desktop／Cursor／その他のクライアント — MCP 設定ファイルに追加します：

{
  "mcpServers": {
    "firefly": {
      "command": "npx",
      "args": ["-y", "@yakupemreyerli/firefly-mcp"],
      "env": { "FIREFLY_API_URL": "your-firefly.example", "FIREFLY_API_TOKEN": "your-token" }
    }
  }
}

2. 静的トークンを使ったリモート HTTP

n8n、自動化、またはブラウザベースの OAuth フローを実行できないクライアント向けです。.env に MCP_HTTP_TOKEN を設定し、npx -y -p @yakupemreyerli/firefly-mcp firefly-mcp-http を実行します。/mcp へのすべてのリクエストには Authorization: Bearer <token> を含める必要があります。トークンは1つで、すべてのアクセスが可能となり、接続ごとの範囲設定はありません。

3. OAuth を使ったリモート HTTP（Claude web、Claude mobile、ChatGPT）

これらのクライアントは静的トークンを保持できず、ローカルプロセスを起動することもできません。公開 HTTPS URL に接続して OAuth を利用します。MCP_AUTH_PASSWORD が設定されている場合、このサーバー自体が OAuth 2.1 認可サーバーになります。クライアント登録、PKCE、トークン交換をすべてサーバーが処理するため、Keycloak も Google サインインも不要で、トークンをどこかにコピーする必要もありません。

手順 1 — サーバーに公開 HTTPS アドレスを設定します。 自宅サーバーの場合は Cloudflare Tunnel が最も簡単です（ポートフォワーディングも証明書も不要です）。VPS では Caddy または Traefik を利用できます。compose.example.yml には、この用途に合わせた cloudflare および caddy プロファイルが用意されています。ここでは、設定後のアドレスを https://mcp.example.com とします。

手順 2 — .env を設定します：

MCP_AUTH_PASSWORD=a-strong-password-of-at-least-12-characters
MCP_RESOURCE_URL=https://mcp.example.com
MCP_AUTH_STATE_DIR=/data/firefly-mcp-auth

MCP_RESOURCE_URL は外部オリジンと文字単位で一致させ、パスを含めないでください。内部アドレスの http://firefly-mcp:3000 でも、接続 URL の /mcp でもありません。一致しない場合、トークンのオーディエンス検証に失敗し、クライアントには「invalid token」とだけ表示されます。MCP_AUTH_STATE_DIR は永続ボリューム上に置く必要があります（compose.example.yml は永続ボリュームをマウントします）。そうしないと、再起動のたびにすべてのクライアントの認可が解除されます。

手順 3 — 起動して確認します：

docker compose -f compose.example.yml up -d
curl https://mcp.example.com/health     # {"ok":true,"auth":"oauth-builtin"}

auth に bearer と表示される場合、パスワードがプロセスに渡されていません。そのため、クライアントにはサーバーが OAuth をサポートしていないと表示されます。

手順 4a — Claude（web、Desktop、iOS／Android）。 Settings → Connectors → Add custom connector を選択し、URL に https://mcp.example.com/mcp を入力します。認証方法は検出された設定のままにしてください。Claude がサーバーを確認し、対応するフローを選択します。コネクターは、スマートフォンを含め、サインインしているすべての Claude 環境で利用できます。

手順 4b — ChatGPT。 カスタムコネクター／MCP の画面で同じ https://mcp.example.com/mcp を入力し、認証方法として OAuth を選択します。

手順 5 — パスワードを入力します。 ブラウザーに Firefly のログイン画面が開くので、MCP_AUTH_PASSWORD を入力します。この画面での選択がすべてです。クライアントが要求したスコープにかかわらず、接続には3つのスコープ（firefly:read、firefly:write、firefly:destructive）すべてが付与されます。追加の同意画面はありません。つまり、パスワードを持つ人は、すべての項目にチェックを入れられるということです。書き込みが本当にできない接続を渡すには、代わりに読み取り専用の Firefly Personal Access Token をサーバーに設定してください。

TLS の完全な設定手順とトラブルシューティングについては、docs/oauth.md を参照してください。

4. Docker

上記いずれかの HTTP モードでの使用におすすめです。

cp .env.example .env    # fill in the values for the mode you need
docker compose -f compose.example.yml up -d

ビルド済みイメージを使用するには、compose.example.yml の build: . を image: ghcr.io/yakupemreyerli/mcp-firefly-iii:latest に置き換えます。依存する用途では、:latest ではなくバージョンタグを固定してください。Compose を使わずに単一のコンテナを起動する場合：docker run -d --env-file .env -p 3000:3000 ghcr.io/yakupemreyerli/mcp-firefly-iii:latest。上記の2つの認証モードのいずれかが設定されていないと起動せず、/mcp の前段には TLS が必要です。そのためのオプションの cloudflare プロファイルと caddy プロファイルが compose.example.yml にあります。コンテナのプローブ用に、/health は認証なしでアクセスできます。

設定

変数	デフォルト	用途
FIREFLY_API_URL	—	必須です。ドメインのみ、または /api/v1 を含む完全なベース URL を指定します。
FIREFLY_API_TOKEN	—	必須です。パーソナルアクセストークンです。
FIREFLY_DISABLE_SSL_VERIFY	false	自己署名証明書を使用するローカルインスタンスの場合のみ指定します。
MCP_UPDATE_CHECK	true	新しいリリースがないか毎日確認します。このサーバーが Firefly インスタンス以外に送る唯一のリクエストで、データは送信されません。

HTTP モードと OAuth モードを含むすべての変数については、docs/configuration.md をご覧ください。

ツール

ツール	できること	リスク
firefly_query	あらゆるデータを読み取ります。説明にカタログが含まれているため、操作を選ぶのに追加の呼び出しは必要ありません。	読み取り専用
firefly_mutate	レコードを作成または変更します。	書き込み
firefly_destructive	レコードを削除するか、多数のレコードの1つのフィールドを一括で書き換えます。	元に戻せません
firefly_list_operations	このエンティティで何ができますか？	読み取り専用
firefly_get_schema	この操作で必要なパラメーターは何ですか？	読み取り専用

この分割は告知だけでなく、実際に強制されます。firefly_query 経由で削除を実行しようとしても拒否され、firefly:read のみを許可された接続には、書き込み用の2つのツールが表示されることもありません。レスポンスはモデルに渡す前に簡潔化されます。空の属性と null の属性は常に除外され、すべての実行ツールで fields リストを指定できます。これにより、トランザクションの大きな一覧では約90％削減できます。完全なリファレンスは、docs/api/operations.md をご覧ください。

セキュリティ

このサーバーがデータを第三者に送信することはありませんが、接続先の AI クライアントやモデルがレスポンスを受け取った後に何をするかは制御できません。脅威モデルの詳細は、SECURITY.md をご覧ください。脆弱性を発見した場合は、そちらから非公開で報告してください。

ドキュメント

ページ	内容
クイックスタート	トークンの取得、クライアントの接続、最初に試すこと、トラブルシューティング
設定	すべての環境変数、権限ポリシー、HTTP モード
埋め込み OAuth によるリモートアクセス	Claude web、Claude mobile、ChatGPT 向けのデプロイ
MCP 統合	Claude Code、Claude Desktop、Cursor、VS Code、n8n、リモート HTTP
操作	全152種類の操作、レスポンスの簡潔化、注意が必要な Firefly の仕様
分析操作	summary.overview、検索、8つのインサイトエンドポイント
MCP Inspector	開発中にサーバーを対話的に試す方法

開発

git clone https://github.com/YakupEmreYerli/mcp-firefly-iii.git && cd mcp-firefly-iii
npm install
cp .env.example .env    # fill in your instance
npm test                # mocked; never touches a live instance
npm run build
npm run check           # read-only connection check against .env

テストはモックを使用しており、ネットワークに接続することはありません。npm run smoke:live は、.env に設定されたインスタンスに対してすべての読み取り操作を実行するメンテナー向けツールです。読み取り専用であり、公開パッケージには含まれていません。バグ報告やプルリクエストを歓迎します。CONTRIBUTING.md をご覧ください。

ライセンス

MIT — LICENSE をご覧ください。

バナーおよび docs/assets/ にある炎と貯金箱のロゴは Firefly III 独自のロゴであり、本ライセンスの対象外です。ロゴのガイドラインで認められているとおり、Firefly III を示すために使用しています。このプロジェクトは Firefly III によって制作または承認されたものではありません。