fineye-mcp — AIエージェントのための、あなたのFinEye財務

非公式・独立。 これは FinEye アプリのAPIに対する、個人利用・コミュニティ製クライアントです。FinEyeとは一切関連をしておらず、FinEyeによる推奨・サポートも受けていません。あなた自身のログインであなた自身のデータにのみ参照します。保証はありません — 自己責任でご利用ください。同梱されているSupabase anon key はアプリのアプリの公開キー（FinEyeクライアントに同梱されている）であり、秘密ではないです。

MCPサーバーです。AIエージェントに、あなたのFinEye of the personal financialデータへの型付けされたアクセスを提供します — 口座、取引、予算、カテゴリ、タグ、保有、支出分析などです。書き込みは明示的な安全ゲートの後ろにあり、削除はさらにその後ろの2つのゲートの後ろにあります。同じコードにはCLIとターミナルダッシュボードも含まれています。

これらは、サンドボックスではなく実際の財務記録です。設計は最初からそれを想定しています。デフォルトモードでは何も削除できず、読み取り専用モードでは書き込みツールを登録することすらせず、破壊的な呼び出しは、あなたが明確に確認するまでは常にプレビューです。

クイックスタート

npm install && npm run build
node dist/index.js login          # Google OAuth, token stored at ~/.config/fineye/session.json
npm link                          # optional: puts `fineye` on your PATH

Claude Codeに登録する:

claude mcp add fineye -s user -- fineye mcp                          # read + write
claude mcp add fineye -s user -e FINEYE_DELETE=1 -- fineye mcp       # read + write + delete
claude mcp add fineye-ro -s user -e FINEYE_READONLY=1 -- fineye mcp  # read-only

他のMCPクライアントでも同じコマンドを使ってください:

{
  "mcpServers": {
    "fineye": {
      "command": "node",
      "args": ["/absolute/path/to/fineye-mcp/dist/index.js", "mcp"],
      "env": {},
    },
  },
}

Related MCP server: YNAB MCP Server

ツール

20個のツールがあります。Therうち10個は読み取り専用です。

どのツールでも、account、category、tag、parent にパラメータが向かう場合は、名前またはIDのどちらでも指定できます。パラメータ名が文字通りidというものは常に生のIDを意味します。

モードとゲート

環境が、サーバーで何ができるかを決めます:

FINEYE_DELETEはサーバー登録時に一度だけ設定され、セッション中はその有効です。つまり、これは確認ではなく権限です。そのため、すべての破壊的呼び出しはまたconfirm: trueを必要とします。これがないと、ツールが削除対象のプレビューを返すだけで、何も変更しません。fineye_bulkはapply: trueがない限りディラム状態のプレビューに留まり、削除するにはapplyとconfirmが両方必要です。

MCPレイヤーの下では、クライアントが動詞ごとの許可リスト（src/client.tsのWRITABLE_TABLES、PATCHABLE_TABLES、DELETABLE_TABLES）適用しています。これ他のテーブルやHTTP動詞は拒否されます。削除には単一のid=eq.<id>しか受け付けられません（大量削除の経路はありません）が、一括削除の場合は先に/tmpにJSONバックアップをしていts>。アカウントとワークスペース設定は決して削除できません。 予定された分割取引は、あなたが求めた場合を除き、一括削除では対象除外れません。

エラーには機械可読なcode（auth、forbidden、not_found、gate、invalid、network、api）が含まれており、エージェントは「その取引は存在しない」と「ネットワーク例外が落ちている」をメッセージ文字列のマーケーションなしに区別できるようになっています。CLIはこれら同じコードを終了ステータス（3, 4, 5, 4, 2, 6, 1）にマッピングしています。

並行編集: 書き込みはJSONフィールドをマージするのではなく、フィールド全体を置き換えます。スマホアプリと同時に同じレコードを編集することは避けましょう — 最後に書き込んだ方が優先されます。

プレイブック

サーバーのinstructionsは、各接続の度に送られるので短時間に頃です。より深いガイダンス — 実際に誤った数値をもたらす落とし穴 — は、タスクが必要になったときにだけ読み込まれます:

• monthly-review — 正しい月次像を得るための呼び出し順序

• safe-bulk-changes — ドライランで実施して、一致件数を検証してから適用する

• test-without-polluting — 作成→実行→削除のできるカナリアテストと、取り消せないもの

• find-and-fix-categories — 自動ルールは未来を修正し、一括修正は過去を修正する

これらはMCPリソース（fineye://playbooks/<id>）しても、fineye_playbookツールでも利用できます。クライアントのリソースサポートが一様ではないためです。データモデルの意味論はCLIエージェントスキル（src/skill/semantics.ts）と共有されており、両者間で乖離を起こすことはありません。

リモートアクセス（HTTP）

ローカルプロセスを起動できないクライアント — 例えばホスティングされたチャットUI — のために、サーバーはStreamable HTTPprotocolにも対応しています:

export FINEYE_MCP_TOKEN=$(openssl rand -hex 24)
fineye mcp --http --port 8790          # binds 127.0.0.1; refuses to start without a token

ヘッダー認証を使って認証します。こうすることで、シークレットがURL、ブラウザ履歴、プロキシログに残りません:

Authorization: Bearer $FINEYE_MCP_TOKEN

クライアントにヘッダーフィールドがない場合は、トークンをURLパス（https://<host>/<token>）としても使えます。誤った資格情報には403ではなく404を返します — 探査者に、そこに何が存在していることを知られないようにするため。

リスナーは、設計上localhostで平文HTTPです。その前にTLSの前段を配置してください — Cloudflare Tunnel、Tailscale Funnel、VPS前のリバースリクシなど、すでに運用しているもので大丈夫です。そして、クライアントからはhttps://<your-host>/mcpを指すようにします。

実行する前に考えてください。これは実際の財務データを、1つのトークンだけで守られた状態で公開し続けるエンドポイントをインターネット上に置くことになります。無人で動かし続けるものにはFINEYE_READONLY=1を選んでください。トークンをスクリーンを撮ることは避け、ファイルを書き換えてからサーバーを再起動することでトークンを交換します。

CLI

人間とシェルスクリプトのための、同じ操作です。

fineye whoami
fineye accounts [--archived] [--json]
fineye networth [--history] [--json]
fineye transactions [--from <date> --to <date> --account <acc> --category <cat> --search <q>] [--json]
fineye analytics [--month YYYY-MM] [--all] [--leaf] [--by-tag] [--by-merchant --top <n>] [--json]
fineye budget [--month YYYY-MM] | fineye budget history [--limit <n>]
fineye export [--format csv|json] [--from --to] [--out <file>]

fineye add expense <amount> --account <acc> [--category --desc --date --fee]
fineye add transfer <amount> --from <acc> --to <acc> [--to-amount <n>]
fineye tx edit <id> [--desc --category --date --hold]
fineye bulk recategorize <filters> --set-category <cat> [--apply]
fineye rule add --merchant "<exact description>" --mcc <code> --category <cat>

金額は口座自身の通貨での小数表示です（例:42.50）。add transferは、アプリと同様に送金元・送金先の両方に同じ金額を書き込みます。実際の送金先の受取金額が異なる場合は--to-amountを渡してください — CLIが独自にレートを適用することはありません。

fineye uiには、ターミナルダッシュボードが起動します。口座と残高、30日のスパークラインを持つ純資産、選択した口座の取引、カテゴリ別の支出チャートが表示されます。

MCPサーバーではなくCLIを使うエージェントのために、さeye skill --installはエージェントスキルを ~/.claude/skills/use-fineye/SKILL.mdに書き込みます。

動作のしくみ

FinEyeは、Supabaseバックエンド上のCapitorアプリです。このクライアントは、アプリと同じPostgRESTテーブルとRPCを使って通信し、あなた自身のGoogleアカウントとしてのPKCE OAuthで認証します（メールOTPはフォールバック）。行レベルセキュリティにより、あなたが自分自身の行だけを参照できます。

このレイヤリングは意図的なものです:

src/domain/*      pure logic: valuation, analytics, transaction shapes, bulk selection
src/client.ts     the only thing that talks HTTP — and where the allow-lists live
src/mcp/*         the MCP surface: tools, resources, instructions, transports
src/commands/*    the CLI surface over the same domain
src/skill/*       data-model semantics, shared by the MCP instructions and the CLI skill

両方のインターフェースが同じドメイン関数を呼び出しているため、CLIと「MCPサーバーのmp」との間で「トランスファーとは何か」や「どの行を使うとしてカウントするのか」が無い違ってくるることかありません。

あ、データに関する事実をここに述べます。これらを間違えると、確信を持った誤った答えを生成してしまうためです。トランザクションにはトップレベルの金額がありません（movements[].sumの合計を使う。支出はマイナスになります）。各口座には固有の通貨があり、数値の合計をサーバー同士で直接比較することはできません。2つのレッグ（足）を持つ動きは、常に自分の口座間の送金を意味します。分割払いプランの将来のレッグにはscheduled`フラグが付いており、実際に支出した金額からは分析の対象外になります。

デベロップメント

npm run typecheck && npm run lint && npm test && npm run build
npm run format

テストスイートはビルド済みのバイナリを起動し、stdioを介して実際のMCPを送信します。これにより、輸送層の配線が「前提」ではなく「テスト保証」されます。

ライセンス

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