satyayeleti/expense-tracker-mcp-server

Expense Tracker MCP Server

A Model Context Protocol (MCP) server that connects AI assistants (like Windsurf/Claude) to your local Flask expense tracker application through natural language commands.

🏗️ What We Built

Architecture Overview

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   AI Assistant  │    │   MCP Server     │    │  Flask App      │
│ (Windsurf/Claude)│◄──►│ (This Project)   │◄──►│ (Port 5000)     │
└─────────────────┘    └──────────────────┘    └─────────────────┘

How It Works

1. You type: "Add ₹5000 salary income" to your AI assistant (Windsurf/Claude)
2. AI Assistant: Interprets this and calls the add_income MCP tool
3. MCP Server: Receives the tool call and makes HTTP POST to Flask app
4. Flask App: Processes the request, updates data.json, returns success
5. Response flows back: Flask → MCP Server → AI Assistant → You see "✅ Income added!"

What the MCP Server Does

• Exposes 4 tools that AI assistants can call
• Translates natural language commands into HTTP API calls
• Communicates via JSON-RPC over stdio (standard input/output)
• Validates parameters and handles errors gracefully

🛠️ Available Tools

1. add_income

Purpose: Add new income entry Parameters: description, amount, category, date (optional) Example: {"description": "Salary", "amount": 50000, "category": "Salary"}

2. add_expense

Purpose: Add new expense entry Parameters: description, amount, category, date (optional) Example: {"description": "Groceries", "amount": 2500, "category": "Food"}

3. get_summary

Purpose: Check if Flask app is running and get status Parameters: None

4. view_data

Purpose: Access transaction data via web interface Parameters: None

🚀 How to Use

Prerequisites

1. Flask App Running:

   cd /home/satya/Projects/windsurf/expense-tracker
   source venv/bin/activate
   python app.py
   

   ✅ Should show: "Running on http://localhost:5000"

2. MCP Server Dependencies:

   cd /home/satya/Projects/windsurf/expense-tracker-mcp-server
   source venv/bin/activate
   pip install -r requirements.txt
   

MCP Server Management

Automatic Management (Windsurf)

When using Windsurf with mcp_config.json:

• Auto-start: Server starts automatically when you use natural language commands
• Auto-stop: Server stops automatically when Windsurf closes or disconnects
• No manual intervention needed: Just use natural language commands!

Manual Management (Testing/Development)

For testing or standalone use:

Starting the Server:

1. Navigate to project directory:

   cd /home/satya/Projects/windsurf/expense-tracker-mcp-server
   

2. Activate virtual environment:

   source venv/bin/activate
   

3. Start the MCP server:

   python expense_tracker_server.py
   

   Note: The server will appear to "hang" - this is normal! It's waiting for JSON-RPC messages via stdin/stdout.

Stopping the Server:

• Keyboard interrupt: Press Ctrl+C to stop the server
• Programmatic: Send SIGTERM signal to the process

Server Status:

• Running: Server waits silently for MCP protocol messages
• Ready: No output means it's ready to receive tool calls
• Error: Any error messages will be displayed in stderr

Testing the MCP Server

Method 1: Automated Testing

cd /home/satya/Projects/windsurf/expense-tracker-mcp-server
source venv/bin/activate
python test_mcp_tools.py

Method 2: Manual Verification

python expense_tracker_server.py
# Server starts and waits (this is expected behavior)
# Press Ctrl+C to exit

Integration with AI Assistants

For Windsurf (Primary Usage)

1. Add MCP server configuration to /home/satya/.codeium/windsurf/mcp_config.json:

   {
    "mcpServers": {
      "expense-tracker": {
        "command": "/home/satya/Projects/windsurf/expense-tracker-mcp-server/venv/bin/python",
        "args": ["/home/satya/Projects/windsurf/expense-tracker-mcp-server/expense_tracker_server.py"],
        "cwd": "/home/satya/Projects/windsurf/expense-tracker-mcp-server"
      }
    }
   

}

2. **Restart Windsurf**

3. **Use natural language commands** (server starts automatically):
- "Add ₹500 grocery expense"
- "Add ₹5000 salary income for today"
- "Show my financial dashboard"
- "Get financial summary"

**Important**: Windsurf automatically starts and manages the MCP server when you use natural language commands. No manual server startup required!

#### For Claude Desktop (Alternative)
1. **Find your Claude Desktop config file**:
- **Linux**: `~/.config/Claude/claude_desktop_config.json`
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

2. **Add the same configuration** as shown above
3. **Restart Claude Desktop**

## 📁 Project Structure

expense-tracker-mcp-server/ ├── expense_tracker_server.py # Main MCP server implementation ├── test_mcp_tools.py # Test script for validation ├── requirements.txt # Python dependencies ├── pyproject.toml # Project configuration ├── README.md # This documentation └── context.md # Project context

## 🔧 Technical Details

### MCP Protocol
- **Communication**: JSON-RPC 2.0 over stdio
- **Initialization**: Server capabilities negotiation
- **Tool Calls**: Structured parameter passing
- **Responses**: Formatted text content

### HTTP Integration
- **Base URL**: http://localhost:5000
- **Endpoints**: /add_income, /add_expense, /, /view_all
- **Method**: POST for data submission, GET for viewing
- **Timeout**: 30 seconds for all requests

### Error Handling
- **Network errors**: Graceful timeout and retry
- **Validation errors**: Clear user feedback
- **Server errors**: Detailed error messages

## 🐛 Troubleshooting

### Common Issues

1. **"Connection refused" errors**
   - **Cause**: Flask app not running
   - **Solution**: Start Flask app at localhost:5000

2. **MCP server hangs when run directly**
   - **Cause**: Normal behavior - uses stdio protocol
   - **Solution**: Use test script or Claude Desktop integration

3. **AI Assistant doesn't see the server**
   - **Cause**: Configuration issues
   - **Solutions**: Check config file path, restart Windsurf/Claude Desktop

### Debug Steps
1. Test Flask app: `curl http://localhost:5000`
2. Test MCP server: `python test_mcp_tools.py`
3. Check AI assistant logs for errors

## 🎯 Learning Outcomes

### What You Learned
1. **MCP Protocol**: How to create servers that extend AI capabilities
2. **API Integration**: Connecting different systems via HTTP
3. **JSON-RPC**: Structured communication protocol
4. **Error Handling**: Robust error management in distributed systems
5. **AI Integration**: How AI assistants can interact with local applications

### Key Concepts
- **Tool Definition**: Describing capabilities with JSON schemas
- **Parameter Validation**: Ensuring data integrity
- **Async Programming**: Non-blocking HTTP requests
- **Protocol Translation**: Converting between MCP and HTTP
- **Natural Language Processing**: AI interpreting commands and calling appropriate tools

## 🚀 Next Steps

1. **Extend Functionality**: Add more tools for reports, categories, etc.
2. **Improve Error Handling**: Add retry logic and better validation
3. **Add Authentication**: Secure the Flask app for production use
4. **Performance Optimization**: Add caching and connection pooling

## 📝 Notes

- This is a **learning project** for understanding MCP servers and AI integration
- The server is designed for **local development** only
- **Security**: No authentication - suitable for localhost only
- **Data Storage**: Flask app uses JSON file storage
- **AI Integration**: Successfully tested with Windsurf (Claude Sonnet 3.5) for natural language expense tracking

---

**Created for learning MCP server development, Flask integration, and AI-powered expense tracking.**
![alt text](image.png)