Expenses Server

An autonomous, production-ready Model Context Protocol (MCP) server built with FastMCP and SQLite3. This server exposes local financial ledger capabilities—adding, listing, and summarizing expenses—to any LLM client (like Claude or LangChain agents) over a remote network connection via Server-Sent Events (SSE).

🚀 Features

Persistent Ledger

Automatically initializes and manages a local expenses.db SQLite instance.

Intelligent Tool Suite

• add_expense: Records transactions with dates, categories, subcategories, and metadata.
• list_expense: Queries transactional history between specific date boundaries.
• summarize: Generates category-wise financial summaries.

Static Resource Routing

Exposes a dedicated expense://categories URI providing JSON schemas of valid budgeting categories.

Remote-Ready Architecture

Switches from traditional Standard I/O (stdio) to a distributed network layer (sse), listening globally on port 8000.

🛠️ Tech Stack

Component	Technology
Language	Python 3.11+
Core Framework	FastMCP (Model Context Protocol SDK)
Database	SQLite3 (Embedded)
Transport Layer	SSE (Server-Sent Events) over HTTP

📦 Installation & Setup

This repository uses uv for lightning-fast Python package and environment management.

1. Clone the Repository

git clone https://github.com/DebarghaNath/remote-mcp-server.git
cd remote-mcp-server

2. Install Dependencies

uv sync

Alternatively:

uv add fastmcp

3. Initialize Configuration Files

Ensure you have a categories.json file in the root folder, or let the server automatically generate a default configuration on its first run.

[
  "Food",
  "Utilities",
  "Entertainment",
  "Housing",
  "Transportation"
]

🏃‍♂️ Running the Server

To launch the remote server and open it up to network traffic, run:

uv run main.py

Upon startup, the terminal will indicate that the SSE server is actively listening:

🚀 Launching Remote Expense Tracker Server on port 8000...
INFO:     Started server process [PID]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)

🔌 Connecting Your Client

To wire this server into an LLM Agent framework (such as LangChain's MultiServerMCPClient or an Anthropic Claude Desktop setup), configure your client transport block using the network endpoint.

LangChain Client Example (client.py)

SERVERS = {
    "expense_tracker": {
        "transport": "sse",
        "url": "http://<SERVER_IP_ADDRESS>:8000/sse"
    }
}

Claude Desktop Configuration (mcp.json)

{
  "mcpServers": {
    "expense-tracker": {
      "command": "uv",
      "args": [
        "run",
        "python",
        "-m",
        "mcp.client.sse",
        "http://localhost:8000/sse"
      ]
    }
  }
}

🔒 Security Note

[!WARNING] Because host="0.0.0.0" binds the server to all network interfaces, anyone who can reach your machine's IP address on port 8000 can read or write to your expense database.

If exposing this outside a home Wi-Fi network, consider placing it behind a reverse proxy (such as Nginx) or a secure VPN tunnel (such as Tailscale).

📄 License

This project is open-source and available under the MIT License.