expense-tracker-mcp

Postgres をバックエンドにした個人支出追跡用のリモート MCP サーバーです。2つの異なるクライアント、つまりコネクタとしての Claude とカスタム LangGraph エージェントから操作できるように設計されています。

「今日、食料品に450使った」と言って支出を記録し、「今月の食費はいくら？」と尋ねると、どちらのクライアントでも同じ答えが得られます。状態がチャットセッションではなくデータベースにあるからです。

Claude (connector) ─┐
                    ├─► expense-tracker-mcp ─► Neon Postgres
LangGraph agent ────┘        (FastMCP)

ステータス

フェーズ1は実際の Neon データベースに対してエンドツーエンドで検証済みです。次のステップはデプロイです。

Related MCP server: expense-tracker-mcp-server

ツール

分類体系はリソースとしても公開されており、expenses://categories です。この重複は意図的なもので、Claude でのテストがきっかけで追加されました。リソースは読み取り専用の参照データに対する正しい MCP プリミティブですが、クライアントがリソースを読むのはユーザーが添付したときだけです。モデルに渡されるのはツールであってリソースではありません。「使えるカテゴリは？」と尋ねると、Claude は分類体系を利用不可と報告し、拒否エラーから有効な値を読み取れるようにダミーの行を書き込もうと提案しました。モデルが実際に到達できるのはツールであり、リソースはリソースを直接閲覧するクライアントのために残されています。

カテゴリは categories.json で定義された固定の2階層分類体系です。20のカテゴリがあり、それぞれにサブカテゴリがあります。分類体系外のものは、エラーに有効な値を含めて拒否されるため、モデルは1往復で自分を修正できます。

ローカルでの実行

前提条件: Python 3.10+、uv、Neon アカウント（無料枠で十分です）。

git clone https://github.com/<your-username>/expense-tracker-mcp
cd expense-tracker-mcp
uv sync

データベースを設定する。 サンプルファイルをコピーして、Neon の接続文字列を入力します：

cp .env.example .env      # PowerShell: Copy-Item .env.example .env

その文字列について重要な点が2つあります：

• プールされた接続を使用する — ホストに -pooler が含まれています。

• ?sslmode=require&channel_binding=require クエリ文字列を削除する。 asyncpg は libpq のクエリパラメータを受け付けず、invalid dsn: invalid connection option "sslmode" を発生させます。代わりに TLS はコード内で明示的に要求されます。（サーバー側でも防御的にこれらを削除するため、そのまま貼り付けた文字列でも動作します。）

テーブルを作成する。 schema.sql を Neon SQL エディタまたは任意の Postgres クライアントで一度実行します。すべてのステートメントは冪等です。

サーバーを起動する：

uv run python main.py            # http://127.0.0.1:8000/mcp

または対話的に探索するには、MCP Inspector を使用します（Node が必要）：

uv run fastmcp dev inspector main.py

ブラウザで /mcp に GET すると 406 Not Acceptable が返ります。これは正しい動作であり、失敗ではありません。MCP は Accept: application/json, text/event-stream を伴う POST を要求するためです。

デプロイ

Prefect Horizon（旧 FastMCP Cloud）向けに構築されています。エントリポイント main.py:mcp でこのリポジトリを指定し、環境変数に DATABASE_URL を設定します。デプロイされたサーバーには *.fastmcp.app URL が付与され、Claude にコネクタとして直接追加できます。

意図的に .python-version ファイルはありません。Horizon は UV_PROJECT_ENVIRONMENT=/usr/local でビルドします。これは virtualenv ではなくシステムの Python プレフィックスです。バージョンを固定すると uv がそれを拒否し、管理された CPython をダウンロードして、venv 以外のディレクトリを再作成しようとして失敗します。pyproject.toml の requires-python = ">=3.10" という下限で十分です。

設計上の決定

金額は NUMERIC(12,2) であり、float は使いません。 2進浮動小数点は 0.1 を正確に表現できないため、float の金額を合計すると誤差が蓄積し、合計がセント単位でずれていきます。金額は Python では Decimal、Postgres では NUMERIC であり、ワイヤ上では文字列として渡されます。JSON の数値は IEEE-754 の double なので、float としてシリアライズすると最後の最後でずれが再発します。450.55 + 120.45 は正確に 571.00 を返します。

接続プールは遅延的に作成され、インポート時には作成されません。 インポート時に接続すると、一時的なデータベースの問題がデプロイの失敗に変わります。遅延プールなら、呼び出し側が再試行できる1回のツール呼び出しの失敗になります。スキーマ作成も同様に、サーバーが起動時に行うものではなく、別の一度きりのスクリプトです。

すべてのパラメータに型注釈が付いています。 FastMCP は型ヒントからモデルが見る JSON スキーマを構築するため、date: date は {"type": "string", "format": "date"} としてモデルに届き、amount には exclusiveMinimum: 0 が付きます。型注釈のないパラメータはツール呼び出しの精度を測定可能なほど低下させます。また、無効な入力はツール本体が実行される前にスキーマ検証で拒否されます。

すべてのツールは成功時も失敗時も dict を返します。ok キーが含まれます。成功時にリスト、エラー時に dict を返すツールは、すべての呼び出し側に結果を使う前の型チェックを強制します。

user_id は最初から存在し、デフォルト値が設定されていますが現在は未使用です。フェーズ4ではすべてのクエリをこれでスコープします。後からデータが入ったテーブルに NOT NULL 列を追加するのはマイグレーションですが、今追加するのはコストゼロです。これは意図的にツールのパラメータにしていません。モデルが user_id を選べると、どのクライアントも尋ねるだけで誰の支出でも読めてしまうからです。

ログは stderr に出力されます。 stdio トランスポートでは、stdout がそのまま JSON-RPC チャネルであり、余計な print() はプロトコルストリームを破壊します。

未実装

見落としではなく、正直な制限です：

• 編集・削除ツールはありません。 誤って記録した支出を修正するには、データベースに直接アクセスする必要があります。実際に不便だと分かるまで延期されています。

• 通貨列はありません。 すべての金額は1つの通貨であると想定されています。

• 認証はありません。 すべての支出は user_id = 'default' として書き込まれるため、デプロイされたサーバーはフェーズ4までシングルテナントです。

レイアウト

main.py           the server: three tools, one resource
schema.sql        one-time table + index creation
categories.json   the category taxonomy, single source of truth
.env.example      documents DATABASE_URL

使用技術

FastMCP 3 · asyncpg · Neon Postgres