Firefly III MCP Server

AI アシスタントに、Model Context Protocol を介して、あなた自身の Firefly III インスタンスへの読み取りアクセス（許可すれば書き込みアクセスも）を提供します。

26のエンティティにわたる146の操作: 取引、口座、予算、カテゴリ、タグ、請求書、貯金箱、ルール、さらに検索と期間分析。

トルコ語: README.tr.md

誰もがこれを自分自身の Firefly インスタンスと自分自身のトークンに対して実行します。何も共有されず、データが第三者を経由することもありません。

インストール

Node.js 20.6+ が必要です。最も簡単な方法は、セットアップに任せることです:

npx -y @yakupemreyerli/firefly-mcp setup

セットアップは Firefly III のアドレスと API トークンを尋ね、それらが実際にあなたのインスタンスに対して動作することを確認し、Claude Code と Claude Desktop が見つかればそれらを設定します。触れたものはすべてバックアップし、他の MCP サーバーには手を付けません。その他のクライアントには、貼り付けるための設定を出力します。

手動で行いたい場合は:

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"
      }
    }
  }
}

トークンは Firefly III → Options → Profile → OAuth → Create New Personal Access Token から取得します。URL はドメインだけで十分です。https:// と /api/v1 は自動的に補完されます。インスタンスがサブパス配下、カスタムポート、または平文の http で動作している場合は、完全な URL を指定してください。

Related MCP server: Firefly III MCP Server

どこまでできるか

stdio 経由では、Firefly トークンが許す範囲まで実行できます。アシスタントに購入の記録や取引のカテゴリ分けを依頼すれば、実行してくれます。サーバー全体の権限設定はありません。質問にしか答えられないセッションが必要な場合は、Firefly III で読み取り専用の Personal Access Token を発行してください。そうすれば、同じ人が編集できる変数ではなく、Firefly 側で制限が強制されます。

HTTP と OAuth を使う場合、アクセスは接続ごとに決定されます。firefly:read、firefly:write、firefly:destructive はパスワード画面で付与され、付与されなかった操作面は拒否されるだけでなく非表示にもなります。

アシスタントが見るもの

ツールは146ではなく5つです。そして実行はリスクごとに分割されているため、ホストは残高の読み取りと取引の削除を区別できます:

各ツールには MCP ツールアノテーション（readOnlyHint、destructiveHint、idempotentHint）が付いており、この分割は単に宣伝されているだけでなく強制されます。firefly_query 経由で到達した削除は拒否されます。firefly:read のみを付与された接続は、2つの書き込みツールをまったく見ることができません。

ほとんどの MCP クライアントは約40ツールを超えると性能が低下するため、サーフェスは3つになっています。

レスポンスはモデルに届く前にトリミングされます。空および null の属性は常に削除され、各実行ツールは fields リストを受け取り、指定した属性だけを保持します。大きな取引リストでは、およそ90%の削減になります。

設定

リモート HTTP モード

プロセスを起動するのではなく HTTP で接続するクライアント（たとえば n8n）向けに、同じサーバーがストリーミング可能な HTTP を話します:

export MCP_HTTP_TOKEN=$(openssl rand -hex 32)
npx -y -p @yakupemreyerli/firefly-mcp firefly-mcp-http

firefly-mcp-http は同じパッケージ内の2番目のバイナリです。そのため npx ではパッケージ名とコマンドを別々に指定するために -p が必要です。

MCP_HTTP_TOKEN がないと起動を拒否し、/mcp へのすべてのリクエストには Authorization: Bearer <token> を付ける必要があります。/health はコンテナのプローブ用に開放されています。Dockerfile と compose.example.yml はリポジトリ内にあります。

TLS の背後に配置してください。トークンは、インターネットとあなたの金融履歴への書き込みアクセスの間にある唯一の防壁です。ポートを直接公開しないでください。

ドキュメント

Docker

HTTP モード用に、linux/amd64 と linux/arm64 向けのビルド済みイメージがあります:

docker run -d \
  -e FIREFLY_API_URL=your-firefly.example \
  -e FIREFLY_API_TOKEN=your-token \
  -e MCP_HTTP_HOST=0.0.0.0 \
  -e MCP_HTTP_TOKEN="$(openssl rand -hex 32)" \
  -p 3000:3000 \
  ghcr.io/yakupemreyerli/mcp-firefly-iii:latest

/health はコンテナのプローブ用にトークンなしで応答します。/mcp 上のすべてには Authorization: Bearer <MCP_HTTP_TOKEN> が必要です。

依存するものには :latest ではなくバージョン（:0.3.1）を固定してください。

開発

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 内のインスタンスに対してすべての読み取り操作を実行します。読み取り専用であり、公開パッケージには含まれません。

コントリビューション

バグ報告とプルリクエストを歓迎します。コードの構成、テストの実行方法、何かに触れる前に知っておくべき Firefly III の癖については、CONTRIBUTING.md を参照してください。

セキュリティ上の問題を発見しましたか? 非公開で報告してください。SECURITY.md を参照してください。

ライセンス

MIT — LICENSE を参照してください。