MCP Agent - AI Expense Tracker

A practical demonstration of AI Agent implementation with custom MCP server.

This project showcases how to build intelligent AI agents using the Model Context Protocol (MCP). Through a real-world expense tracking application, you'll see how AI agents can interact with tools, databases, and APIs to perform complex tasks through natural conversation.

🎯 What This Demonstrates

• Custom MCP Server: Build your own MCP server using FastAPI

• AI Agent Integration: Connect AI agents to tools via MCP protocol

• Real-world Application: Practical expense tracking use case

• Natural Language Interface: Chat with AI to manage your data

• Tool Discovery: AI automatically discovers and uses available tools

🏗️ Architecture

📖 For detailed architecture documentation, request flows, and deployment options, see

🚀 Features

• AI-Powered Agent: Natural language expense tracking using OpenAI GPT-4

• SQLite Database: Persistent storage for all transactions

• Auto-Initialization: Automatic database setup with seed data

• MCP Integration: Extensible tool system for AI agents

• REST API: Full CRUD operations for expense management

• Multiple Clients: Web UI, Telegram bot, and direct agent interface

• Smart Categorization: Automatic expense categorization and insights

• Currency-Agnostic: Clean numerical formatting without currency symbols

📁 Project Structure

🏃 Quick Start

1. Install Dependencies

2. Set Environment Variables

3. Initialize and Start Servers

4. Run the AI Agent

Access the agent at: http://localhost:7777

💬 Usage Examples

Chat with the AI agent:

• "Add a 50 grocery expense"

• "I spent 75 on dinner last night"

• "How much did I spend on food this month?"

• "Show me my financial summary"

• "What's my biggest expense category?"

• "Add income of 5000 from salary"

🛠️ Tech Stack

• Protocol: Model Context Protocol (MCP) - Custom server implementation

• Agent Framework: Agno

• AI Model: OpenAI GPT-4

• MCP Server: FastAPI-MCP (converts REST API to MCP tools)

• Backend: FastAPI + SQLite

• Frontend: Next.js + React

• Bot: Python Telegram Bot

🔌 How MCP Works Here

1. FastAPI Backend (server/main.py) - Standard REST API with CRUD operations

2. MCP Server (server/mcp_server.py) - Wraps the API and exposes it as MCP tools

3. AI Agent (agent/agent.py) - Connects to MCP server and automatically discovers tools

4. Natural Language - User chats with agent, agent uses tools to complete tasks

📊 API Endpoints

• GET /transactions - List all transactions

• POST /transactions - Create new transaction

• PUT /transactions/{id} - Update transaction

• DELETE /transactions/{id} - Delete transaction

• GET /transactions/search?q= - Search transactions

• GET /summary - Financial summary

• GET /summary/categories - Category breakdown

• GET /health - Health check

Full API docs: http://localhost:8002/docs

🎯 Server Commands

The start.py script manages server initialization and startup:

What

• ✅ Checks all required dependencies

• ✅ Verifies environment variables

• ✅ Initializes SQLite database

• ✅ Seeds database with sample transactions (first run only)

• ✅ Starts requested server(s)

🤖 Agent Capabilities

The AI agent can:

• Create, read, update, and delete expenses

• Search transactions by keyword

• Generate financial summaries and insights

• Analyze spending patterns by category

• Provide budgeting recommendations

• Filter transactions by date, type, or category

🔧 Configuration

Environment Variables (.env)

Server Configuration (server/config.py)

• Server host/port settings

• Database path

• MCP server configuration

Agent Configuration (agent/agent.py)

• AI model selection (default: gpt-4.1)

• System prompt customization

• Agent behavior settings

• Database location

🔍 Troubleshooting

Dependencies missing?

Database not initialized?

Port already in use?

Agent can't connect to MCP?

• Ensure MCP server is running: python start.py --mcp

• Check MCP URL in agent/agent.py (default: http://localhost:9002/mcp)

📊 Presentation

This project includes a presentation about practical AI agent implementation:

🌐 Live Demo

View Slides Online →

📁 Local Files

• English Slides: docs/en/index.html

• Russian Slides: docs/ru/index.html

Open the slides to learn more about AI agents and MCP protocol.

📚 Resources

This project is built with and inspired by amazing open-source projects:

• Model Context Protocol (MCP) - Standard protocol for connecting AI agents to tools

• FastAPI-MCP - FastAPI integration for MCP servers

• Agno - Modern framework for building AI agents

• Agent UI - Beautiful chat interface for AI agents

Special thanks to these projects and their maintainers for making AI agent development accessible and enjoyable! 🙏

📝 License

MIT

Built with ❤️ using AI agents and MCP