📊 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' formatcategoria: 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! 🚀