# 💰 Expense Tracker Remote MCP Server
 
A simple **Model Context Protocol (MCP) server** built with **Python and FastMCP** that provides tools for managing and analyzing personal expenses through an SQLite database.
 
The server supports adding expenses, retrieving expenses within a date range, summarizing expenses by category, and accessing available expense categories as an MCP resource.
 
---
 
## 🚀 Features
 
- ➕ Add new expense records
- 📋 List expenses within a specific date range
- 📊 Summarize expenses by category
- 🗂️ Expose expense categories through an MCP resource
- 💾 Persistent storage using SQLite
- 🌐 Runs as a remote/HTTP MCP server
- 🔌 Compatible with MCP clients and MCP Inspector
- ⚡ Built with FastMCP
---
 
## 🛠️ Tech Stack
 
- **Python**
- **FastMCP**
- **Model Context Protocol (MCP)**
- **SQLite**
- **uv** – Python package/project manager
- **JSON**
---
 
## 📁 Project Structure
 
```text
Expense_Tracker_Remote_MCP_Server/
│
├── src/
│   └── test_remote_mcp_server/
│       └── __init__.py
│
├── categories.json
├── expenses.db
├── main.py
├── pyproject.toml
├── uv.lock
├── .gitignore
└── README.md
```
 
### Important Files
 
| File | Purpose |
|---|---|
| `main.py` | Main MCP server implementation |
| `expenses.db` | SQLite database containing expense records |
| `categories.json` | Expense category data |
| `pyproject.toml` | Project dependencies and configuration |
| `uv.lock` | Locked dependency versions |
| `.gitignore` | Files excluded from Git |
| `README.md` | Project documentation |
 
---
 
## ⚙️ How It Works
 
The MCP server uses FastMCP to expose expense-management functionality as MCP tools.
 
```
                    MCP Client
                        │
                        ▼
                FastMCP MCP Server
                        │
          ┌─────────────┼─────────────┐
          ▼             ▼             ▼
    add_expense    list_expenses   summarize
          │             │             │
          └─────────────┼─────────────┘
                        ▼
                   SQLite DB
                  expenses.db
```
 
The server also exposes:
 
```
expense://categories
```
 
as an MCP resource for retrieving available expense categories.
 
---
 
## 🔧 MCP Tools
 
### 1. `add_expense`
 
Adds a new expense to the SQLite database.
 
**Parameters**
 
| Parameter | Type | Required | Description |
|---|---|---|---|
| `date` | string | Yes | Date of the expense |
| `amount` | number | Yes | Expense amount |
| `category` | string | Yes | Expense category |
| `subcategory` | string | No | Expense subcategory |
| `note` | string | No | Additional note |
 
**Example**
 
```python
add_expense(
    date="2026-08-29",
    amount=250,
    category="Food",
    subcategory="Lunch",
    note="Lunch at college"
)
```
 
Example response:
 
```json
{
  "status": "ok",
  "id": 1
}
```
 
### 📋 2. `list_expenses`
 
Returns expense records within an inclusive date range.
 
**Parameters**
 
| Parameter | Type | Required | Description |
|---|---|---|---|
| `start_date` | string | Yes | Starting date |
| `end_date` | string | Yes | Ending date |
 
**Example**
 
```python
list_expenses(
    start_date="2026-08-01",
    end_date="2026-08-29"
)
```
 
Example response:
 
```json
[
  {
    "id": 1,
    "date": "2026-08-29",
    "amount": 250,
    "category": "Food",
    "subcategory": "Lunch",
    "note": "Lunch at college"
  }
]
```
 
### 📊 3. `summarize`
 
Summarizes expenses by category within an inclusive date range.
 
An optional category can be provided to filter the results.
 
**Parameters**
 
| Parameter | Type | Required | Description |
|---|---|---|---|
| `start_date` | string | Yes | Starting date |
| `end_date` | string | Yes | Ending date |
| `category` | string | No | Optional category filter |
 
**Example**
 
```python
summarize(
    start_date="2026-08-01",
    end_date="2026-08-29"
)
```
 
Example response:
 
```json
[
  {
    "category": "Food",
    "total_amount": 2500
  },
  {
    "category": "Transport",
    "total_amount": 1200
  }
]
```
 
You can also filter by category:
 
```python
summarize(
    start_date="2026-08-01",
    end_date="2026-08-29",
    category="Food"
)
```
 
---
 
## 🗂️ MCP Resource
 
The server exposes the following resource:
 
```
expense://categories
```
 
This resource reads the contents of:
 
```
categories.json
```
 
The file is read each time the resource is requested, meaning category changes can be reflected without restarting the server.
 
---
 
## 💾 Database
 
The server uses SQLite for persistent expense storage.
 
The database contains the following table:
 
**expenses**
 
with the following columns:
 
| Column | Type | Description |
|---|---|---|
| `id` | INTEGER | Primary key |
| `date` | TEXT | Expense date |
| `amount` | REAL | Expense amount |
| `category` | TEXT | Expense category |
| `subcategory` | TEXT | Expense subcategory |
| `note` | TEXT | Additional information |
 
The database table is automatically created when the server starts if it does not already exist.
 
---
 
## 🧰 Installation
 
### Prerequisites
 
Make sure you have:
 
- Python 3.10+
- uv
- Git
### 1. Clone the repository
 
```bash
git clone https://github.com/abhisek0407/Expense_Tracker_Remote_MCP_Server.git
cd Expense_Tracker_Remote_MCP_Server
```
 
### 2. Install dependencies
 
If the project already contains `pyproject.toml` and `uv.lock`:
 
```bash
uv sync
```
 
---
 
## ▶️ Run the MCP Server
 
The server is configured to run using Streamable HTTP on port 8000.
 
Start the server with:
 
```bash
uv run python main.py
```
 
The server will listen on:
 
```
http://localhost:8000
```
 
The MCP endpoint is:
 
```
http://localhost:8000/mcp
```
 
---
 
## 🔍 Test With MCP Inspector
 
You can test the server locally using MCP Inspector.
 
In another terminal:
 
```bash
uv run fastmcp dev inspector main.py
```
 
Then configure the Inspector with:
 
- **Transport Type:** Streamable HTTP
- **URL:** `http://localhost:8000/mcp`
- **Connection Type:** Via Proxy
Click **Connect**.
 
Once connected, the Inspector should expose:
 
**Tools**
- `add_expense`
- `list_expenses`
- `summarize`
**Resource**
- `expense://categories`
---
 
## 🌐 Remote Deployment
 
This project can be deployed as a remote MCP server using a platform such as FastMCP Cloud.
 
The server uses:
 
```python
mcp.run(
    transport="http",
    host="0.0.0.0",
    port=8000
)
```
 
This allows the MCP server to accept HTTP connections instead of only operating through STDIO.
 
After deployment, the MCP server can be accessed through the remote endpoint provided by the hosting platform.
 
For example:
 
```
https://your-server.fastmcp.app/mcp
```
 
The actual URL depends on the server name and deployment configuration.
 
---
 
## 🔐 Environment Variables
 
Currently, the server does not require any external API keys or authentication credentials.
 
If authentication or external services are added in the future, environment variables can be configured through the deployment platform.
 
---
 
## 🧪 Example Workflow
 
A typical interaction with the MCP server can look like:
 
```
User
 │
 │ "Add ₹500 spent on food today"
 ▼
MCP Client
 │
 │ add_expense()
 ▼
Expense Tracker MCP Server
 │
 ▼
SQLite Database
 │
 │ Expense stored
 ▼
MCP Response
 │
 ▼
MCP Client
```
 
For analysis:
 
```
User
 │
 │ "How much did I spend by category this month?"
 ▼
MCP Client
 │
 │ summarize()
 ▼
Expense Tracker MCP Server
 │
 ▼
SQLite
 │
 │ GROUP BY category
 ▼
Category-wise totals
```
 
---
 
## 📌 Current Limitations
 
- No authentication mechanism is currently implemented.
- The server currently uses a local SQLite database.
- No user/account separation is implemented.
- Date values are stored as text and should follow a consistent date format such as `YYYY-MM-DD`.
- Categories are loaded from a local `categories.json` file.
---
 
## 🚧 Future Improvements
 
Possible improvements include:
 
- 🔐 Authentication and authorization
- 👤 Multiple user support
- ☁️ Cloud database integration
- 📈 Advanced expense analytics
- 💰 Budget tracking
- 🔔 Budget alerts
- 📅 Monthly and yearly reports
- 📊 Spending visualization
- 🏷️ Custom categories
- 🤖 AI-powered spending insights
- 🧾 Receipt processing
- 💱 Multi-currency support
---
 
## 🎯 Purpose of the Project
 
This project was created to learn and demonstrate the implementation of an MCP server using FastMCP, including:
 
- MCP tools
- MCP resources
- SQLite integration
- HTTP/Streamable HTTP transport
- Local MCP server testing
- MCP Inspector
- Remote MCP server deployment
It serves as a practical example of connecting an AI/MCP client with a persistent backend application.
 
---
 
## 📄 License
 
This project is available for educational and personal use.