MCP Server (Budget Tracker)

A local Model Context Protocol (MCP) server for recording and querying budget expenses. Data is stored in the included DuckDB database.

Contents

• server.py — FastMCP server and budget tools
• database.py — DuckDB connection and schema helpers
• budget.duckdb — local persisted budget data
• pyproject.toml and uv.lock — Python dependencies

Windows installation

These instructions run the server in WSL 2 (Ubuntu) and connect it to Claude Desktop on Windows. This is the supported setup documented here; native Windows and macOS instructions can be added separately later.

1. Install prerequisites

Install the following:

1. WSL with an Ubuntu distribution. Confirm it is available from PowerShell:

   wsl -l -v
   

2. Claude Desktop for Windows.

3. In your Ubuntu (WSL) terminal, install Python 3.10 or later, Node.js 20 or later, npm, and uv:

   sudo apt update
   sudo apt install -y python3 python3-pip python3-venv curl
   curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
   sudo apt install -y nodejs npm
   python3 -m pip install --user uv
   

   Close and reopen the Ubuntu terminal if uv is not yet on your PATH.

2. Set up the project in WSL

Clone or copy this repository into your WSL home directory. For example:

mkdir -p ~/mcp_server
cd ~/mcp_server
# Copy the project files here, then install the locked dependencies.
uv sync

uv sync creates the virtual environment and installs FastMCP and DuckDB from the project’s lock file.

To confirm the installation and start the server locally:

uv run fastmcp version
uv run server.py

For interactive inspection during development, run:

uv run fastmcp dev server.py

3. Add the server to Claude Desktop

In Claude Desktop, open Settings → Developer → Open config folder. Open (or create) claude_desktop_config.json. Common Windows locations are:

C:\Users\\AppData\Roaming\Claude\claude_desktop_config.json
C:\Users\\AppData\Local\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\claude_desktop_config.json

Add this server definition. Replace Ubuntu with the distribution name reported by wsl -l -v, and replace /home//mcp_server with the directory where you placed this project.

{
  "mcpServers": {
    "budget-tracker": {
      "command": "wsl.exe",
      "args": [
        "-d",
        "Ubuntu",
        "bash",
        "-lc",
        "cd /home//mcp_server && uv run server.py"
      ]
    }
  }
}

If the file already contains an mcpServers object, add only the budget-tracker entry inside it. Ensure the resulting file remains valid JSON.