Expense Tracker Remote MCP Server

A production-grade Model Context Protocol (MCP) server for recording, tracking, filtering, and analyzing personal and organizational expenses. Built with FastMCP and Clean Architecture principles.

Architecture Overview

src/remote_mcp/
├── domain/                  # Entities, Value Objects, Repository Contracts, Exceptions
│   ├── entities.py          # Expense, ExpenseSummary, ExpenseFilter
│   ├── exceptions.py        # Typed Domain Exceptions
│   └── repository.py        # ExpenseRepository Protocol
├── application/             # Use Case Orchestration & Business Rules
│   └── service.py           # ExpenseTrackerService
└── infrastructure/          # Data Access & External Integrations
    └── sqlite_repository.py # SQLite with WAL mode & parameterized queries
main.py                      # FastMCP Entrypoint exposing Tools & Resources

Related MCP server: Expense Tracker MCP Server

Available Tools

Available Resources

• expenses://summary: JSON overview of total expenditure, record count, and category breakdown.

• expenses://categories: JSON mapping of categories to total spending.

• info://server: Server metadata and active capabilities.

Getting Started

Prerequisites

• Python 3.13+

• uv

Installation

uv sync

Running the Server

Run directly with Python (HTTP transport on 0.0.0.0:8080):

uv run python main.py

Or run via FastMCP CLI:

uv run fastmcp run main.py --transport http --host 0.0.0.0 --port 8080

Testing & Verification

Run the test suite:

uv run pytest -v

Using with MCP Inspector

1. Start the inspector:

   npx @modelcontextprotocol/inspector

2. In the inspector UI:

   • Select Streamable HTTP

   • Connect to http://127.0.0.1:8080/mcp