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

Related MCP server: Calculator MCP Server

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)

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:

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

Windows: PowerShell and scripts

Server / dev inspector

Claude Desktop: MCP does not connect or server errors

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