expense-mcp

A minimal FastMCP server that exposes demo tools for arithmetic and dice rolls. Use it to learn MCP wiring with Claude Desktop or other MCP clients.

Requirements

• Python 3.13+ (see .python-version / pyproject.toml)
• uv for environments and dependency management

Setup with uv (step by step)

Follow these in order on a machine that does not have the project set up yet.

1. Install uv

Pick the official installer for your OS. Common one-liners:

Windows (PowerShell):

irm https://astral.sh/uv/install.ps1 | iex

macOS / Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Close and reopen the terminal (or reload your shell profile) so uv is on your PATH.

2. Confirm uv

uv --version

3. Get the code

Clone the repository and move into it (use your real clone URL or path):

git clone <repository-url> expense-mcp
cd expense-mcp

If you already have the folder unpacked, just cd to the repo root (where pyproject.toml lives).

4. (Optional) Install a matching Python with uv

If you do not have Python 3.13 available, uv can fetch one:

uv python install 3.13

The repo’s .python-version pins 3.13; uv sync will respect that when creating the environment.

5. Create the virtual environment and install dependencies

From the repo root:

uv sync

This will:

• Create .venv if it is missing (or update it to match the lockfile)
• Install packages from pyproject.toml using versions from uv.lock

If you prefer to create the venv yourself first (optional):

uv venv --python 3.13
uv sync

6. (Optional) Activate the virtual environment

You do not need activation if you always use uv run … (recommended). To activate:

• Windows (PowerShell): .venv\Scripts\Activate.ps1
• Windows (cmd): .venv\Scripts\activate.bat
• macOS / Linux: source .venv/bin/activate

7. Verify the install

uv run fastmcp --version
uv run python --version

You should see a FastMCP version and Python 3.13.x.

Quick reference (after setup)

Goal	Command
Reinstall deps from lockfile	uv sync
Add a new dependency	uv add <package>
Refresh uv.lock after editing pyproject.toml	uv lock
Run a one-off command in the project env	uv run <command>

Run the server

Development / inspector (useful for debugging tools in the browser):

uv run fastmcp dev inspector main.py

Production-style run (stdio transport for MCP clients):

uv run fastmcp run main.py

Direct Python (stdio, same entry as if __name__ == "__main__"):

uv run python main.py

Tools (API)

Defined in main.py:

Tool	Description
roll_dice	Rolls n_dice six-sided dice; returns integers.
add_numbers	a + b
subtract_numbers	a - b
multiply_numbers	a * b

Docstrings on each function are what MCP clients show as tool descriptions.

Install into Claude Desktop

uv run fastmcp install claude-desktop main.py

Then:

1. Restart Claude Desktop fully (quit the app, not only the window).
2. In settings, ensure the expense-mcp (or similarly named) server is enabled.
3. If the install command errors (especially on Windows), see Claude Desktop: config path / install fails.

Troubleshooting

Use this section when something fails or behaves unexpectedly. Work from the top of each subsection that matches your symptom.

uv and Python

Symptom	What to try
uv is not recognized	Install uv (see Setup), then restart the terminal. Confirm install docs for your OS put uv on PATH.
uv sync fails or wrong Python	Run uv python install 3.13, then uv sync again from the repo root (folder that contains pyproject.toml).
Packages seem missing	From repo root: uv sync. Prefer uv run <command> so the project .venv is used; avoid mixing in a global python without the venv.
“No pyproject.toml” or wrong deps	cd to the repository root before uv sync / uv run.

Windows: PowerShell and scripts

Symptom	What to try
Running .venv\Scripts\Activate.ps1 fails (“running scripts is disabled”)	For your user only: Set-ExecutionPolicy -Scope CurrentUser RemoteSigned in PowerShell, then retry. Or use cmd and .\venv\Scripts\activate.bat.
Activation not needed	Using uv run … from the repo root avoids activation entirely.

Server / dev inspector

Symptom	What to try
ModuleNotFoundError or wrong fastmcp	Run with uv run (e.g. uv run fastmcp dev inspector main.py), not a system-wide python that never had deps installed.
Inspector / dev command errors	Run from repo root; pass main.py or a path that exists. If a port is busy, close other inspector sessions or see FastMCP docs for port options.
Stdio server exits immediately	In a terminal: uv run fastmcp run main.py or uv run python main.py and read the traceback. Fix any import or config error before wiring Claude again.

Claude Desktop: MCP does not connect or server errors

Symptom	What to try
Server disabled	Settings → MCP: turn on the expense-mcp entry; restart Claude.
Wrong working directory	The MCP process must run with cwd (or equivalent) set to this repo so main.py and .venv resolve. Re-run uv run fastmcp install claude-desktop main.py or edit claude_desktop_config.json so the launched command’s working directory is the project root.
uv not found when Claude starts	Use the full path to uv.exe in config, or ensure the user PATH seen by the desktop app includes uv (often differs from your interactive terminal).
JSON config mistakes	Open claude_desktop_config.json in an editor with JSON validation. One missing comma breaks the whole file.

Manual config shape (illustrative) — names and keys follow your Claude Desktop version; adjust paths:

"mcpServers": {
  "expense-mcp": {
    "command": "C:\\Users\\you\\AppData\\Local\\Programs\\uv\\uv.exe",
    "args": ["run", "fastmcp", "run", "main.py"],
    "cwd": "C:\\path\\to\\expense-mcp"
  }
}

On macOS/Linux use forward slashes and typical uv location from which uv. Re-installing via fastmcp install is usually easier than hand-editing.

Claude Desktop: config path or install fails (Windows Store and paths)

Classic path (many installers): %APPDATA%\Claude (contains claude_desktop_config.json).

Microsoft Store build often uses:

%LOCALAPPDATA%\Packages\Claude_<id>\LocalCache\Roaming\Claude

If fastmcp install claude-desktop says Claude has no config folder or cannot find it:

1. Environment variable — set the directory that actually holds claude_desktop_config.json (names depend on FastMCP version):

   • FASTMCP_CLAUDE_DESKTOP_CONFIG_DIR, or
   • CLAUDE_DESKTOP_CONFIG_DIR
     Then run uv run fastmcp install claude-desktop main.py again in the same terminal session.

2. Patch in .venv (advanced) — Patching fastmcp\cli\install\claude_desktop.py under .venv can teach the installer to scan Packages\Claude_*\LocalCache\Roaming\Claude. Any later uv sync or fresh venv removes that patch — re-apply or use option 1 or 3.

3. Directory junction — If %APPDATA%\Claude does not already exist as a real folder, junction it to the Store path (adjust <your-id>; may need an elevated cmd):

   mklink /J "%APPDATA%\Claude" "%LOCALAPPDATA%\Packages\Claude_<your-id>\LocalCache\Roaming\Claude"
   

   Then run uv run fastmcp install claude-desktop main.py again.

Upstream FastMCP may add first-class support for the Store layout so patching or junctions are unnecessary.

Assistant answers without using your tools

A normal-looking answer (e.g. “8 + 10 = 18”) does not prove the MCP ran. Check for tool-use in the UI or force a unique tool.

1. UI — Look for a tool / “used …” step, not only the final message.
2. Explicit instruction — e.g. “Use the add_numbers tool from expense-mcp for 8 and 10 and state that you used the tool.”
3. Unique tool — e.g. “Call roll_dice with n_dice=4.” Matching tool name and die results implicates this server (unless another MCP defines the same tool name).
4. Proof tool — Add a tiny tool in main.py that returns a string only this project would emit; call it once and compare the tool output.

Patches or local edits under .venv disappeared

Anything changed only inside .venv (including hand-patched FastMCP files) is replaced when you run uv sync, delete .venv, or reinstall deps. Prefer env vars, junctions, or documented config over long-lived venv edits; otherwise re-apply the patch after each sync.

Project layout

Path	Role
main.py	FastMCP server and @mcp.tool definitions
pyproject.toml	Package metadata and dependencies
uv.lock	Locked dependency versions