Expense Tracker MCP Server

A Model Context Protocol (MCP) server built with FastMCP (v3.x) and Python, designed to provide tools and resources for expense tracking to MCP-compliant clients like Claude Desktop and the MCP Inspector.

📋 Prerequisites

Python: 3.10+ (tested with Python 3.14)
uv: Fast Python package installer and resolver (astral.sh/uv)
Node.js: v22.x or v24.x (LTS) — Required for MCP Inspector UI
Claude Desktop (optional): For testing tools directly within Claude

🚀 Setup & Installation

1. Initialize Project & Environment

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

# Install FastMCP
uv add fastmcp

2. Prepare Node.js for MCP Inspector UI

The MCP Inspector (@modelcontextprotocol/inspector) requires Node.js v22.19.0+ or v24+. If using nvm-windows:

nvm install lts
nvm use 24

Install the inspector globally or allow npx to fetch it:

npm install -g @modelcontextprotocol/inspector

🛠️ Running & Development

Option A: Interactive Web UI (MCP Inspector)

To launch the MCP Inspector web UI with hot reloading:

uv run fastmcp dev inspector main.py

Keep this terminal window open.

The console will output a local URL with an authentication token:

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

Open that link in your browser to test tools, inspect schemas, and view real-time request/response logs.

Option B: Run Server Directly (STDIO)

To run the MCP server in standard I/O mode:

uv run fastmcp run main.py

(or uv run python main.py)

🤖 Connecting to Claude Desktop

1. Configuration File Location

On Windows, Claude Desktop's configuration is stored at:

%APPDATA%\Claude\claude_desktop_config.json

(Full path: C:\Users\<YourUsername>\AppData\Roaming\Claude\claude_desktop_config.json)

2. Configuration Settings

Add the expense-server definition under mcpServers.

Note: On Windows, GUI applications like Claude Desktop often do not inherit the shell PATH. Always specify the absolute path to 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. Restart Claude Desktop

Completely close Claude Desktop (ensure it is quit from the Windows system tray near the clock).
Reopen Claude Desktop.
Check Settings > Developer to verify expense-server is connected.

🧰 Available Tools (Current `main.py`)

Tool	Parameters	Description
`roll_dice`	`n_dice: int = 1`	Rolls `n_dice` 6-sided dice and returns results list.
`add_numbers`	`a: float, b: float`	Adds two numbers together and returns the sum.

🔧 Troubleshooting

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

In FastMCP 3.x, fastmcp dev is a command group. Use fastmcp dev inspector main.py instead of fastmcp dev main.py.

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

Node.js is older than v20.12. Update to Node v22+ or v24+ via nvm install lts && nvm use 24.

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

Corrupted npx cache from switching Node versions. Run:

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

Expense Tracker MCP Server