📊 MCP Server - Personal Expense Manager

An MCP (Model Context Protocol) server for managing and analyzing personal expenses from CSV files.

🚀 Features

Add expenses to a CSV file with categorization
Get recent expenses with day-based filtering
MCP Resource for direct access to all expenses
Specialized prompt that generates automatic analytical summaries
Analysis by category and payment method
Trend detection and spending patterns

📋 Requirements

pip install fastmcp mcp

🗂️ Project Structure

expenses-mcp-server/ ├── server.py # Main MCP server ├── data/ │ └── expenses.csv # Expenses file (created automatically) ├── requirements.txt └── README.md

🛠️ Installation & Usage

1. Clone or create the project

mkdir expenses-mcp-server cd expenses-mcp-server

2. Create virtual environment (recommended)

python -m venv venv source venv/bin/activate # Linux/Mac # or venv\Scripts\activate # Windows

3. Install dependencies

pip install fastmcp mcp

4. Run the server

python server.py

🔧 Available Functionalities

Tools

1. `agregar_gasto` (Add Expense)

Adds a new expense to the system.

Parameters:

fecha: Date in 'YYYY-MM-DD' format
categoria: Expense category (e.g., "Food", "Transport")
cantidad: Expense amount (float)
metodo_pago: Payment method used

Example:

agregar_gasto("2024-01-15", "Groceries", 150.75, "Debit Card")

2. `obtener_gastos_recientes` (Get Recent Expenses)

Gets expenses from the last N days.

Parameters:

dias: Number of days to query (default: 5)

Example:

obtener_gastos_recientes(7) # Last 7 days

Resource

`resource://gastos`

Direct access to all stored expenses.

Specialized Prompt

`Resumen de Gastos Recientes` (Recent Expenses Summary)

Generates a prompt with structured data for AI to create a complete analysis including:

📈 Statistical calculations (totals, averages)
🏷️ Category analysis
💳 Payment method distribution
🔍 Trend identification
💡 Personalized recommendations

📊 CSV Structure

The data/expenses.csv file has the following structure:

fecha,categoria,cantidad,metodo_pago 2024-01-15,Groceries,150.75,Debit Card 2024-01-16,Transport,45.50,Cash 2024-01-17,Entertainment,89.99,Credit Card

🔌 MCP Client Integration

Python Client Example

import asyncio from mcp import ClientSession, StdioServerParameters from mcp.client.stdio import stdio_client async def main(): server_params = StdioServerParameters( command="python", args=["server.py"] ) async with stdio_client(server_params) as (read, write): async with ClientSession(read, write) as session: # Initialize session await session.initialize() # Add expense result = await session.call_tool( "agregar_gasto", { "fecha": "2024-01-18", "categoria": "Restaurant", "cantidad": 85.50, "metodo_pago": "Credit Card" } ) print(result) # Get recent expenses expenses = await session.call_tool( "obtener_gastos_recientes", {"dias": 5} ) print(expenses) if __name__ == "__main__": asyncio.run(main())

🎯 Use Cases

1. Daily Expense Tracking

# Add transport expense agregar_gasto("2024-01-18", "Transport", 35.00, "Cash") # Add food expense agregar_gasto("2024-01-18", "Food", 120.00, "Debit Card")

2. Weekly Analysis

# Get last week summary obtener_gastos_recientes(7)

3. Monthly Report

# Complete 30-day analysis obtener_gastos_recientes(30)

📈 Example Generated Analysis

The specialized prompt generates analysis like:

📊 EXPENSE SUMMARY - LAST 5 DAYS 💰 TOTAL SPENT: $1,245.75 📅 DAILY AVERAGE: $249.15 🔢 TRANSACTIONS: 8 purchases 🏷️ CATEGORY DISTRIBUTION: • Groceries: 45% ($560.25) • Transport: 25% ($311.44) • Entertainment: 20% ($249.15) • Restaurant: 10% ($124.58) 💳 PAYMENT METHODS: • Credit Card: 60% • Debit Card: 30% • Cash: 10% 📈 OBSERVATIONS: • Highest spending on Wednesday ($420.50) • "Groceries" category represents almost half of expenses • Growing trend in credit card usage 💡 RECOMMENDATIONS: • Consider bulk purchases to reduce grocery expenses • Diversify payment methods for better control • Set weekly limit for entertainment

🛠️ Troubleshooting

Error: "FileNotFoundError"

Ensure the data/ directory exists
Server creates the file automatically with the first expense

Error: "Encoding issues"

Server uses UTF-8 for special character compatibility

Error: "Invalid date format"

Use exact format: YYYY-MM-DD
Example: 2024-01-18

📝 License

MIT License

📞 Support

For issues and questions, open a ticket in the project repository.

Start tracking your expenses intelligently! 🚀

Personal Expense Manager

📊 MCP Server - Personal Expense Manager

🚀 Features

📋 Requirements

🗂️ Project Structure

🛠️ Installation & Usage

1. Clone or create the project

2. Create virtual environment (recommended)

3. Install dependencies

4. Run the server

🔧 Available Functionalities

Tools

1. `agregar_gasto` (Add Expense)

2. `obtener_gastos_recientes` (Get Recent Expenses)

Resource

`resource://gastos`

Specialized Prompt

`Resumen de Gastos Recientes` (Recent Expenses Summary)

📊 CSV Structure

🔌 MCP Client Integration

Python Client Example

🎯 Use Cases

1. Daily Expense Tracking

2. Weekly Analysis

3. Monthly Report

📈 Example Generated Analysis

🛠️ Troubleshooting

Error: "FileNotFoundError"

Error: "Encoding issues"

Error: "Invalid date format"

📝 License

📞 Support

Resources

New MCP Servers

Latest Blog Posts

MCP directory API

📊 MCP Server - Personal Expense Manager

🚀 Features

📋 Requirements

🗂️ Project Structure

🛠️ Installation & Usage

1. Clone or create the project

2. Create virtual environment (recommended)

3. Install dependencies

4. Run the server

🔧 Available Functionalities

Tools

1. agregar_gasto (Add Expense)

2. obtener_gastos_recientes (Get Recent Expenses)

Resource

resource://gastos

Specialized Prompt

Resumen de Gastos Recientes (Recent Expenses Summary)

📊 CSV Structure

🔌 MCP Client Integration

Python Client Example

🎯 Use Cases

1. Daily Expense Tracking

2. Weekly Analysis

3. Monthly Report

📈 Example Generated Analysis

🛠️ Troubleshooting

Error: "FileNotFoundError"

Error: "Encoding issues"

Error: "Invalid date format"

📝 License

📞 Support

Resources

New MCP Servers

Latest Blog Posts

MCP directory API

1. `agregar_gasto` (Add Expense)

2. `obtener_gastos_recientes` (Get Recent Expenses)

`resource://gastos`

`Resumen de Gastos Recientes` (Recent Expenses Summary)