MCPAgent

dev-muhammad/MCPAgent

3.3

If you are the rightful owner of MCPAgent and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The Model Context Protocol (MCP) server is a custom implementation designed to facilitate the interaction between AI agents and various tools, databases, and APIs through natural language processing.

MCP Agent - AI Expense Tracker

License: MIT Python 3.11+ GitHub stars Presentation

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

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

🚀 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

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

# Install Python dependencies
pip install -r server/requirements.txt
pip install agno openai python-dotenv

2. Set Environment Variables

# Copy example and add your API key
cp .env.example .env
# Edit .env and add your OPENAI_API_KEY

3. Initialize and Start Servers

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

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
  • 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
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:

# 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)

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?

pip install -r server/requirements.txt
pip install agno openai python-dotenv

Database not initialized?

cd server && python start.py

Port already in use?

python start.py --api --port 8003
python start.py --mcp --port 9003

Agent can't connect to MCP?

📊 Presentation

This project includes a presentation about practical AI agent implementation:

🌐 Live Demo

View Slides Online →

📁 Local Files

  • English Slides:
  • Russian Slides:

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:

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