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.

Restart Claude Desktop. In a new chat, select the Budget Tracker connection from the connection menu.

4. Try it out

Ask Claude, for example:

• “Add a $45.50 grocery expense from yesterday.”
• “I spent $1,200 on rent on the 1st.”
• “Show me my spending by category for June.”
• “What is my monthly spending trend for the last three months?”

macOS installation

These instructions run the server with a Conda environment and connect it to Claude Desktop on macOS.

1. Create and activate a Conda environment

Install Miniconda if Conda is not already available. From the project directory, create and activate an environment with Python 3.12:

conda create --name env_poc python=3.12
conda activate env_poc

2. Install the server dependencies

From the mcp project directory, install FastMCP and DuckDB into the active Conda environment:

python -m pip install "duckdb>=1.5.4" "fastmcp>=3.4.2"

Verify that both packages import successfully:

python -c "import duckdb, fastmcp; print('Dependencies installed successfully')"

3. Test the server

Start the server:

python server.py

The server uses the MCP standard-input/output transport and may appear to wait without further output. This is expected. Press Control+C to stop the test server before continuing.

4. Add the server to Claude Desktop

Open (or create) Claude Desktop’s configuration file:

mkdir -p "$HOME/Library/Application Support/Claude"
touch "$HOME/Library/Application Support/Claude/claude_desktop_config.json"
open -a TextEdit "$HOME/Library/Application Support/Claude/claude_desktop_config.json"

Add the following entry to the top-level mcpServers object. First, use which python while env_poc is active to obtain the exact Conda Python path. Replace both example paths below with paths on your Mac:

{
  "mcpServers": {
    "budget-tracker": {
      "command": "/opt/homebrew/Caskroom/miniconda/base/envs/env_poc/bin/python",
      "args": [
        "/Users//path/to/mcp/server.py"
      ]
    }
  }
}

If claude_desktop_config.json already contains settings such as preferences, add mcpServers as a new top-level key; do not place it inside preferences. If an mcpServers object already exists, add only the budget-tracker entry to it. Ensure the file remains valid JSON.

5. Connect and test in Claude Desktop

Fully quit and reopen Claude Desktop. In a new chat, open the + menu, choose Connectors, and select Budget Tracker.

Do not run python server.py in Terminal while Claude Desktop is connected: both processes would attempt to access the same DuckDB file.

Ask Claude, for example:

• “Add a $45.50 grocery expense from yesterday.”
• “I spent $1,200 on rent on the 1st.”
• “Show me my spending by category for June.”

Notes

• Budget data is stored locally in budget.duckdb.
• Run only one copy of the server at a time. DuckDB locks the database file while the server is running.