Expense Tracker MCP Server

FastMCP (v3.x) と Python で構築された Model Context Protocol (MCP) サーバーで、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: Demo 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)

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

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\\hp\\AppData\\Local\\Python\\pythoncore-3.14-64\\Scripts\\uv.exe",
      "args": [
        "run",
        "--directory",
        "g:\\Projects\\expense-tracker-mcp-server",
        "fastmcp",
        "run",
        "main.py"
      ]
    }
  }
}

3. Claude Desktop を再起動する

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

2. Claude Desktop を開き直します。

3. Settings > Developer で、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