Fintable MCP

fintable-mcp

fintable.io 向けの非公式 MCP（Model Context Protocol）サーバーです。Claude などの AI アシスタントを使って、複数の手順からなるウィザードをクリックして進めることなく、金融カテゴリ、ルール、取引を直接管理できます。

注記：これはコミュニティプロジェクトであり、fintable.io の公式サポート対象ではありません。ブラウザーのセッションを使って、Fintable の Laravel Livewire 3 バックエンドと通信します。Fintable の開発者の方で、公式 MCP サーバーやパブリック API の開発にご協力いただける場合は、ぜひ Issue を作成してください。ぜひ一緒に取り組みたいと考えています！🤝

---

できること

インストールすると、Claude やお好みの MCP クライアントに、次のようなことを依頼できます。

• 「次の経費カテゴリを作成して：Office Supplies、Shipping、Packaging、Equipment Rental、Software Subscriptions」
• 「ルールを作成して：『Staples』→ Office Supplies、『UPS』→ Shipping、『USPS』→ Shipping」
• 「すべてのルールを実行して、取引をカテゴリ分けして」
• 「Ally Bank の現在の口座残高はいくら？」
• 「カテゴリ分けルールをすべて一覧表示して」

20 個のカテゴリを設定するために、3 ページのウィザードを 20 回も進める必要はありません。必要なことを Claude に伝えるだけです。

---

提供するツール

読み取り操作

ツール	説明
fintable_list_accounts	残高とともに、接続済みの銀行口座をすべて一覧表示します
fintable_list_categories	すべての取引カテゴリを一覧表示します
fintable_list_rules	カテゴリ分けルールを一覧表示します（ページネーション対応）
fintable_list_transactions	任意のフィルタリングを指定して、取引を一覧表示／検索します

書き込み操作

ツール	説明
fintable_create_category	単一のカテゴリを作成します
fintable_create_bulk_categories	一度に最大 50 個のカテゴリを作成します
fintable_create_rule	カテゴリ分けルールを作成します
fintable_create_bulk_rules	複数のルールを一度に作成します
fintable_run_all_rules	カテゴリ未設定の取引に対して、すべてのルールを実行します
fintable_delete_rule	カテゴリ分けルールを削除します
fintable_sync_accounts	Plaid 経由で銀行口座の同期を開始します
fintable_resync_spreadsheets	Airtable／Google Sheets に更新を反映します

---

インストール

前提条件

• Python 3.10+
• 銀行口座を接続した fintable.io アカウント
• Claude Desktop（または Cherry Studio など、MCP 対応クライアント）

1. このリポジトリをクローンする

git clone https://github.com/jasoncbraatz/fintable-mcp.git
cd fintable-mcp

2. 依存関係をインストールする

pip install -r requirements.txt

または uv を使う方法（より高速）：

uv pip install -r requirements.txt

3. 認証の設定

自動（推奨）または手動の2つの方法があります。

オプション A：Cookie の自動抽出（推奨）

rookiepy をインストールします。OS の認証情報を使って、Chrome のローカルデータベースから Cookie を直接読み取ります。

pip install rookiepy

以上です。Chrome で fintable.io にログインしていれば、サーバーは実行のたびに新しい Cookie を取得します。手動でコピーする必要も、有効期限を気にする必要もありません。

オプション A½：自動更新される Cookie jar（上級者向け）

Chrome や rookiepy を初回以降に使わずに、サーバーに独自のセッションを維持させたい場合は、設定に --persist-cookies フラグを追加します（手順 4 を参照）。セッション Cookie は ~/.fintable-mcp-cookies.json に保存され、サーバーの応答から自動更新されます。実行の間にサーバー側でセッションが期限切れにならない限り、セッションは維持されます。

初期データは、利用可能な認証方法（rookiepy、環境変数など）から取得されます。その後は、サーバーだけで動作します。

セキュリティに関する注意：セッション Cookie はディスクに保存されます。このファイルはホームディレクトリ内のドットファイルで、どこにも公開されませんが、ホームフォルダーへの読み取りアクセス権がある人なら見つけられます。気になる場合は、オプション A をご利用ください。

Python 3.13 以降をご利用の場合：rookiepy のインストール前に PYO3_USE_ABI3_FORWARD_COMPATIBILITY=1 の設定が必要になることがあります。

PYO3_USE_ABI3_FORWARD_COMPATIBILITY=1 pip install rookiepy

オプション B：Cookie の手動エクスポート

rookiepy をインストールしたくない場合や、Chrome 以外のブラウザーを使っている場合は、次の手順で Cookie をエクスポートします。

1. Chrome を開いて fintable.io にアクセスし、ログインしていることを確認します
2. DevTools を開きます（F12 または Cmd+Option+I）
3. Network タブを開きます
4. fintable.io へのリクエストを選択します
5. Request Headers 内の Cookie ヘッダーを探します
6. Cookie 文字列全体をコピーします

次の手順で、これを環境変数として渡します。

4. Claude Desktop の設定

次の内容を Claude Desktop の設定ファイルに追加します。

macOS：~/Library/Application Support/Claude/claude_desktop_config.json Windows：%APPDATA%\Claude\claude_desktop_config.json

rookiepy を使う場合（オプション A） — 環境変数は不要です。

{
  "mcpServers": {
    "fintable": {
      "command": "python",
      "args": ["/absolute/path/to/fintable-mcp/fintable_mcp.py"]
    }
  }
}

--persist-cookies を使う場合（オプション A½） — 初期データの取得には、rookiepy または環境変数を併用します。

{
  "mcpServers": {
    "fintable": {
      "command": "python",
      "args": ["/absolute/path/to/fintable-mcp/fintable_mcp.py", "--persist-cookies"]
    }
  }
}

手動で Cookie を設定する場合（オプション B）：

{
  "mcpServers": {
    "fintable": {
      "command": "python",
      "args": ["/absolute/path/to/fintable-mcp/fintable_mcp.py"],
      "env": {
        "FINTABLE_COOKIES": "your_full_cookie_string_here"
      }
    }
  }
}

💡 /absolute/path/to/fintable-mcp/fintable_mcp.py を、このリポジトリをクローンした実際のパスに置き換えてください。

5. Claude Desktop を再起動する

設定を保存したら、Claude Desktop を完全に終了してから再起動します。fintable ツールが Claude のツール一覧に表示されます。

---

認証

このサーバーは、fintable.io のブラウザーセッション Cookie を使って認証します。これは、ログイン中にブラウザーが使用するものと同じ Cookie です。

Cookie の解決順序：

0. 保存済み Cookie jar — --persist-cookies が有効で、~/.fintable-mcp-cookies.json に新しい Cookie がある場合は、それを使用します。サーバーの Set-Cookie ヘッダーから自動更新されます。
1. rookiepy — インストールされている場合、サーバーの起動ごとに Chrome のローカルデータベースから新しい Cookie を抽出します。メンテナンスは不要です。
2. FINTABLE_COOKIES 環境変数 — Chrome DevTools から取得した Cookie 文字列全体です（rookiepy がインストールされていない場合のフォールバック）。
3. FINTABLE_SESSION_COOKIE 環境変数 — セッション Cookie の値のみです（最も簡単な手動設定方法）。

--persist-cookies が有効な場合、初期 Cookie を提供する方法のいずれから取得した場合でも、その Cookie が jar の初期データになります。次回以降は jar が優先され、サーバーの応答のたびに自動で更新されます。

このサーバーが認証情報をディスクに保存することはありません — サーバーの実行中、認証情報はメモリー内にのみ保持されます。

セッションの有効期限

**rookiepy（推奨）**を使用している場合、セッションの有効期限は自動的に管理されます。サーバーを起動するたびに、Chromeから新しいクッキーが取得されます。Chromeで fintable.io にログインした状態を維持してください。

クッキーを手動でエクスポートしている場合、クッキーはいずれ期限切れになります。期限切れになると、サーバーは認証エラーを返します。Chromeからクッキーを再エクスポートし、環境変数 FINTABLE_COOKIES を更新してください。

---

仕組み（詳しく知りたい方向け／開発者向け）

Fintable.io は、フロントエンドに Livewire 3 と Alpine.js を使用した Laravel アプリケーションで、公開 REST API はありません。この MCP サーバーは次のように動作します。

1. ブラウザーのセッションクッキー（CSRF トークン＋セッションクッキー）を使って認証します
2. ページを取得し、HTML 属性 wire:snapshot から Livewire コンポーネントのスナップショットを抽出します
3. コンポーネントのスナップショット、メソッド呼び出し、プロパティの更新を含む POST リクエストを /livewire-{hash}/update エンドポイントに送信し、Livewire プロトコルの呼び出しを行います
4. HTML の応答を解析し、構造化データ（口座、カテゴリ、ルール、取引）を抽出します

Livewire の更新パスにはハッシュ（例：/livewire-5c7ce5a8/update）が含まれ、アプリの再デプロイ時に変わることがあります。サーバーは各ページの読み込み時に data-update-uri HTML 属性からこのパスを自動検出するため、デプロイ後も安定して動作します。

---

既知の問題と制限事項

Livewire のハッシュ変更

Livewire の更新エンドポイントにはビルドハッシュ（例：/livewire-5c7ce5a8/update）が含まれ、デプロイのたびに変わります。サーバーはページを取得するたびにこれを自動検出しますが、Fintable が Livewire コンポーネントを大幅に再構成したり、コンポーネント名を変更したりすると、動作しなくなる可能性があります。これは公式 API を使わずに動作させることに伴う避けられない問題です。

HTML 解析の脆弱性

JSON API がないため、読み取り操作は HTML 構造の解析に依存します。Fintable が UI のレイアウトを再設計すると、解析ロジックの更新が必要になる場合があります。これは現在のアプローチにおける最大の保守負担です。

今後の展望：JSON エンドポイント

理想的な解決策は、Fintable が軽量な JSON API エンドポイントを公開することです。これにより、次のことが可能になります。

• 脆弱な HTML 解析をなくせます
• Livewire のハッシュへの依存をなくせます
• より信頼性の高い連携を実現できます
• ほかのコミュニティ製ツールや連携の可能性が広がります
• 製品の大きなアピールポイントになります（MCP 対応の金融ツールは差別化要因です！）

これを読んでいる Fintable の開発者の方へ。カテゴリ、ルール、取引用に、認証が必要な JSON エンドポイントをいくつか用意するだけでも、このサーバーは非常に堅牢になり、保守も大幅に容易になります。設計についてぜひ一緒に検討しましょう。🚀

---

セキュリティモデル

このサーバーは、MCP クライアントの stdio サブプロセスとして、お使いのマシン上でローカルに動作します。次の特徴があります。

• ネットワークポートを公開しません
• 認証情報をディスクに保存しません
• 既存のブラウザーセッションを使って fintable.io と通信するだけです
• 単一ユーザー、単一クライアントのプロセスとして動作します

デフォルトでは、セッションクッキーはサーバーの実行中のみメモリ上に保持されます。rookiepy を使用すると、起動のたびに Chrome から新たに取得されるため、環境変数や設定ファイルは必要ありません。

--persist-cookies を有効にすると、クッキーは ~/.fintable-mcp-cookies.json（ホームディレクトリ内のドットファイル）に保存されます。これは、クッキーがディスク上に残ることと引き換えに、セッションを自動更新できる利便性を得るオプトイン方式です。ファイルを削除すれば、いつでもセッションを無効にできます。

---

貢献

プルリクエストを歓迎します！今後の改善案をいくつか紹介します。

• 取引の日付範囲によるフィルタリングのサポート
• カテゴリグループの管理（グループの作成／名前変更）
• ルールの優先順位の並べ替え
• バックアップ用にカテゴリ／ルールを JSON としてエクスポート
• 複数の Fintable アカウントのサポート

**削除に関する注意：**カテゴリの削除は意図的にサポートしていません。これは破壊的な操作であり、影響全体を確認できる Fintable のウェブ UI から行うのが最適です。削除の前に少し手間がかかることは、バグではなく機能です。

---

免責事項

このプロジェクトは、fintable.io との提携、承認、または公式サポートを受けていません。Livewire 3 のフロントエンドプロトコルをリバースエンジニアリングして構築されました。ご自身の責任でご利用ください。基盤となる Livewire プロトコルは、予告なく変更される場合があります。

ライセンス

MIT - Jason C Braatz