Expense Tracker MCP Server

Model Context Protocol (MCP) サーバーで、FastMCP (v3.x) と Python で構築され、Claude Desktop や MCP Inspector などの MCP 準拠クライアントに経費追跡のためのツールとリソースを提供するように設計されています。

📋 前提条件

• Python: 3.10+ (Python 3.14 でテスト済み)

• uv: 高速な Python パッケージインストーラー兼リゾルバー (astral.sh/uv)

• Node.js: v22.x または v24.x (LTS) — MCP Inspector UI に必要

• Claude Desktop (任意): Claude 内で直接ツールをテストするため

Related MCP server: Math Addition MCP Server

🚀 セットアップとインストール

1. プロジェクトと環境の初期化

# Initialize uv project (if starting fresh)
uv init .

# Install FastMCP
uv add fastmcp

2. MCP Inspector UI 用に Node.js を準備する

MCP Inspector (@modelcontextprotocol/inspector) には Node.js v22.19.0+ または v24+ が必要です。nvm-windows を使用している場合:

nvm install lts
nvm use 24

インスペクターをグローバルにインストールするか、npx にフェッチを許可してください:

npm install -g @modelcontextprotocol/inspector

🛠️ 実行と開発

オプション A: インタラクティブ Web UI (MCP Inspector)

ホットリロード 付きで MCP Inspector Web UI を起動するには:

uv run fastmcp dev inspector main.py

• このターミナルウィンドウを開いたままにしてください。

• コンソールは認証トークン付きのローカル URL を出力します:

  MCP Inspector Web is up and running at:
     http://127.0.0.1:6274?MCP_INSPECTOR_API_TOKEN=<token>

• そのリンクをブラウザで開いて、ツールのテスト、スキーマの確認、リアルタイムのリクエスト/レスポンスログの表示を行ってください。

オプション B: サーバーを直接実行 (STDIO)

MCP サーバーを標準 I/O モードで実行するには:

uv run fastmcp run main.py

(または uv run python main.py)

🤖 Claude Desktop への接続

1. 設定ファイルの場所

Windows では、Claude Desktop の設定は次の場所に保存されます:

%APPDATA%\Claude\claude_desktop_config.json

(完全なパス: C:\Users\<YourUsername>\AppData\Roaming\Claude\claude_desktop_config.json)

2. 設定

mcpServers の下に expense-server 定義を追加します。

注: Windows では、Claude Desktop などの GUI アプリケーションはシェルの PATH を継承しないことがよくあります。常に uv.exe への絶対パスを指定してください。

{
  "mcpServers": {
    "expense-server": {
      "command": "C:\\Users\\pyash\\AppData\\Local\\Python\\pythoncore-3.14-64\\Scripts\\uv.exe",
      "args": [
        "run",
        "--directory",
        "d:\\expense-tracker-mcp-server",
        "fastmcp",
        "run",
        "main.py"
      ]
    }
  }
}

3. Claude Desktop を再起動する

1. Claude Desktop を完全に閉じます (時計の近くの Windows システムトレイから終了していることを確認してください)。

2. Claude Desktop を再度開きます。

3. 設定 > 開発者 を確認して、expense-server が接続されていることを確認します。

🧰 利用可能なツール (現在の main.py)

🔧 トラブルシューティング

1. Unknown command "main.py". Available commands: inspector, apps.

FastMCP 3.x では、fastmcp dev はコマンドグループです。fastmcp dev main.py の代わりに fastmcp dev inspector main.py を使用してください。

2. node:util does not provide an export named 'styleText'

Node.js が v20.12 より古いです。nvm install lts && nvm use 24 で Node v22+ または v24+ に更新してください。

3. Cannot find native binding (npm optional dependencies bug)

Node バージョンの切り替えによる npx キャッシュの破損。次を実行してください:

npm cache clean --force
Remove-Item -Recurse -Force "$env:LOCALAPPDATA\npm-cache\_npx" -ErrorAction SilentlyContinue
npm install -g @modelcontextprotocol/inspector