MCP Agent - AI Expense Tracker

# MCP Agent - AI Expense Tracker [](https://opensource.org/licenses/MIT) [](https://www.python.org/downloads/) [](https://github.com/dev-muhammad/MCPAgent) [](https://dev-muhammad.github.io/MCPAgent/) **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 ```mermaid graph TB subgraph "Backend" API[API Server<br/>FastAPI + SQLite<br/>Port: 8002] MCP[MCP Server<br/>FastAPI-MCP<br/>Port: 9002] end subgraph "AI Layer" Agent[AI Agent<br/>Agno Framework<br/>Port: 7777] LLM[LLM] end subgraph "Client Layer" UI[Web UI<br/>Next.js + React<br/>Port: 3000] Telegram[Telegram Bot<br/>Python Telegram Bot] AnyClient[Any MCP Client] end subgraph "End Users" User1[User] User2[User] User3[User] end API -->|Exposes REST API| MCP MCP -->|MCP Protocol| Agent MCP -.->|MCP Protocol| AnyClient Agent -->|API Calls| LLM Agent -->|Serves| UI Agent -->|Serves| Telegram UI -->|Interacts| User1 Telegram -->|Interacts| User2 AnyClient -.->|Interacts| User3 style API fill:#0066CC,color:#fff style MCP fill:#00AA66,color:#fff style Agent fill:#FF6600,color:#fff style LLM fill:#8B5CF6,color:#fff style UI fill:#06B6D4,color:#fff style Telegram fill:#06B6D4,color:#fff ``` > 📖 **For detailed architecture documentation, request flows, and deployment options, see [ARCHITECTURE.md](ARCHITECTURE.md)** ## 🚀 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 ```text MCPAgent/ ├── .env.example # Environment variables template ├── .env # Your configuration (create from .env.example) ├── agent/ # AI Agent with Agno framework │ ├── agent.py # Main agent with system prompts │ └── agno.db # Agent's SQLite database ├── server/ # FastAPI backend with MCP server │ ├── main.py # API routes and endpoints │ ├── store.py # SQLite data store │ ├── models.py # Pydantic data models │ ├── config.py # Configuration settings │ ├── mcp_server.py # MCP protocol server │ ├── start.py # Server initialization & startup │ └── expenses.db # Transactions database └── client/ ├── agent-ui/ # Next.js web interface └── telegram-bot/ # Telegram bot client ``` ## 🏃 Quick Start ### 1. Install Dependencies ```bash # Install Python dependencies pip install -r server/requirements.txt pip install agno openai python-dotenv ``` ### 2. Set Environment Variables ```bash # Copy example and add your API key cp .env.example .env # Edit .env and add your OPENAI_API_KEY ``` ### 3. Initialize and Start Servers ```bash cd server # Check dependencies and initialize database with seed data python start.py # Start MCP server (in one terminal) python start.py --mcp # Start API server (in another terminal) python start.py --api ``` ### 4. Run the AI Agent ```bash cd agent python agent.py ``` 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](<https://docs.agno.com/>) - **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 ```text User Input → AI Agent → MCP Server → FastAPI → SQLite ↓ Tool Selection & Execution ↓ Natural Language Response ``` ## 📊 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: ```bash # Check dependencies and initialize database python start.py # Start MCP server only python start.py --mcp # Start API server only python start.py --api # Custom ports python start.py --api --port 8000 python start.py --mcp --port 9000 ``` **What `start.py` does:** - ✅ 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`) ```bash OPENAI_API_KEY=your_key_here # Required for AI agent HOST=localhost # Server host PORT=8002 # API server port MCP_HOST=localhost # MCP server host MCP_PORT=9002 # MCP server port ``` ### 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?** ```bash pip install -r server/requirements.txt pip install agno openai python-dotenv ``` **Database not initialized?** ```bash cd server && python start.py ``` **Port already in use?** ```bash python start.py --api --port 8003 python start.py --mcp --port 9003 ``` **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 →](https://dev-muhammad.github.io/MCPAgent/)** ### 📁 Local Files - **English Slides**: [docs/en/index.html](docs/en/index.html) - **Russian Slides**: [docs/ru/index.html](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)](https://modelcontextprotocol.io)** - Standard protocol for connecting AI agents to tools - **[FastAPI-MCP](https://github.com/jlowin/fastapi-mcp)** - FastAPI integration for MCP servers - **[Agno](https://docs.agno.com)** - Modern framework for building AI agents - **[Agent UI](https://github.com/agno-agi/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