# Expense Tracker MCP

[![M8ven Score](https://m8ven.ai/badge/mcp/khushisonwane23-expense-tracker-mcp-qszpws)](https://m8ven.ai/mcp/khushisonwane23-expense-tracker-mcp-qszpws)

A remote **Model Context Protocol (MCP) server** built with **FastMCP** that allows AI assistants such as Claude to interact with an expense-tracking system through structured tools.

##  Overview

This project demonstrates how an AI assistant can interact with external data and application functionality through MCP.

The Expense Tracker MCP server uses **FastMCP** to expose expense-management tools and **SQLite** to store expense data.

The server is deployed remotely using **FastMCP Cloud**, allowing an MCP-compatible client such as Claude to connect to it through a remote MCP endpoint.

##  Architecture

```text
Claude
   │
   │ MCP
   ▼
Remote MCP Endpoint
   │
   ▼
FastMCP Cloud
   │
   ▼
FastMCP Expense Tracker Server
   │
   ▼
SQLite Database
```

##  Features

* Add and manage expenses
* Retrieve expense records
* Categorize expenses
* Store expense data using SQLite
* Expose expense functionality through MCP tools
* Deploy the MCP server remotely
* Connect the remote MCP server to Claude
* Allow AI assistants to interact with structured expense data

##  Tech Stack

* Python
* FastMCP
* Model Context Protocol (MCP)
* SQLite
* JSON
* FastMCP Cloud
* Claude

##  Example Interactions

Once connected to Claude, users can interact with the expense tracker using natural language.

```text
"Add an expense of ₹500 for groceries."

"Show me my recent expenses."

"How much did I spend on food?"

"List my expenses by category."
```

Claude interprets the user's request and invokes the appropriate MCP tool exposed by the server.

##  Remote Deployment

The MCP server is deployed on **FastMCP Cloud** and exposed through a remote MCP endpoint.

This allows Claude and other MCP-compatible clients to access the server without running it locally.

```text
Local Development
       ↓
FastMCP Server
       ↓
FastMCP Cloud
       ↓
Remote MCP Endpoint
       ↓
Claude
```

##  Local Setup

Clone the repository:

```bash
git clone https://github.com/khushisonwane23/expense-tracker-mcp.git
cd expense-tracker-mcp
```

Create a virtual environment:

```bash
python -m venv .venv
```

Activate the virtual environment on Windows:

```bash
.venv\Scripts\activate
```

Install dependencies:

```bash
pip install -r requirements.txt
```

If you are using `uv`:

```bash
uv sync
```

##  Run Locally

Run the FastMCP server:

```bash
fastmcp run server.py
```

The exact command may vary depending on the project configuration.

## 🔗 Connecting to Claude

After deploying the server to FastMCP Cloud, the application provides a remote MCP endpoint.

This endpoint can be configured in an MCP-compatible client such as Claude.

```text
Claude
   ↓
Remote MCP Endpoint
   ↓
FastMCP Cloud
   ↓
Expense Tracker MCP Server
   ↓
SQLite Database
```

Once connected, Claude can discover and use the tools exposed by the MCP server.

##  Security

Sensitive information should never be committed to this repository.

The following files should remain private:

```text
.env
expenses.db
.venv/
__pycache__/
```

API keys and other secrets should be stored using environment variables instead of being hard-coded in the source code.

##  Learning Goals

This project was built to understand:

* How the Model Context Protocol works
* How AI assistants interact with external tools
* How to build MCP servers using FastMCP
* How to connect LLMs with external data
* How tool-based AI workflows work
* How to deploy an MCP server remotely
* How MCP can be integrated with Claude

##  Future Improvements

* Add authentication and authorization
* Add monthly spending analytics
* Add budget tracking
* Add richer financial insights
* Improve error handling and input validation
* Add automated testing
* Use a production-grade database
* Add more financial management tools

##  Author

**Khushi Sonwane**

Artificial Intelligence & Robotics Student

Interested in **Generative AI, AI Agents, MCP, RAG, and AI Research**.