haris-khan-dev/MCP-server

FastAPI + MCP + Gemini Integration

This project demonstrates how to integrate a FastAPI application with Google's Gemini AI using a simplified MCP (Model Context Protocol) server implementation.

🏗️ Architecture

• FastAPI App (app.py): A sample REST API with user management, task management, and dice rolling
• Simple MCP Server (simple_mcp_server.py): Simplified MCP server that exposes FastAPI endpoints as tools
• Gemini Integration (simple_gemini_integration.py): Connects Gemini AI with the MCP server

🚀 Features

FastAPI Application

• User management (CRUD operations)
• Task management with completion tracking
• Dice rolling functionality
• Health checks and statistics
• RESTful API endpoints

MCP Server Tools

• get_health_status(): Check application health
• get_app_info(): Get application information
• get_all_users(): Retrieve all users
• create_user(): Create new users
• get_user_by_id(): Get specific user
• get_all_tasks(): Retrieve all tasks
• create_task(): Create new tasks
• complete_task(): Mark tasks as completed
• roll_dice(): Roll dice with custom parameters
• get_app_statistics(): Get application statistics
• search_users_by_name(): Search users by name
• get_pending_tasks(): Get incomplete tasks
• get_completed_tasks(): Get completed tasks

📋 Prerequisites

• Python 3.8+
• Google Gemini API key (optional - demo works in simulation mode)
• Basic Python packages (fastapi, uvicorn, aiohttp, google-generativeai)

🛠️ Installation

1. Clone or download the project files

2. Install dependencies:

   pip install fastapi uvicorn aiohttp google-generativeai python-dotenv requests
   

3. Set up environment variables (optional): Create a .env file and add your Gemini API key:

   GEMINI_API_KEY=your_actual_api_key_here
   

   Note: The demo works without an API key in simulation mode.

4. Get a Gemini API key:

   • Visit Google AI Studio
   • Create a new API key
   • Add it to your .env file

🎯 Usage

0. Look for the video demo

You can look for the zip file in which screen recording is present. That includes a demo question and an answer.

1. Start the FastAPI Server

python app.py

The FastAPI server will run on http://localhost:8000

2. Test the FastAPI Endpoints

You can test the API directly:

# Health check
curl http://localhost:8000/health

# Get app info
curl http://localhost:8000/

# Create a user
curl -X POST "http://localhost:8000/users?name=John&email=john@example.com&age=30"

# Create a task
curl -X POST "http://localhost:8000/tasks?title=Learn%20FastMCP&description=Study%20FastMCP%20integration"

# Roll dice
curl "http://localhost:8000/dice/roll?sides=6&count=3"

3. Run the Gemini Integration

Demo Mode (Predefined Queries)

python simple_gemini_integration.py

Interactive Mode

python simple_gemini_integration.py --interactive

Automated Demo

python start_simple_demo.py

4. Example Gemini Queries

In interactive mode, you can ask questions like:

• "Check the health status of the FastAPI application"
• "Create a new user named 'Alice' with email 'alice@example.com' and age 25"
• "Create a task called 'Learn Python' with description 'Study Python programming'"
• "Roll 5 dice with 10 sides each"
• "Show me all users and get the application statistics"
• "Mark the first task as completed"
• "Show me all pending tasks"

🔧 Configuration

FastAPI Server

• Default port: 8000
• Host: 0.0.0.0 (accessible from all interfaces)
• Modify app.py to change these settings

MCP Server

• Connects to FastAPI server at http://localhost:8000
• Modify API_BASE_URL in mcp_server.py if needed

Gemini Integration

• Uses Gemini 2.0 Flash model
• Configure API key via environment variable
• Modify model settings in gemini_integration.py

📁 Project Structure

.
├── app.py                        # FastAPI application
├── simple_mcp_server.py         # Simplified MCP server with tools
├── simple_gemini_integration.py # Gemini + MCP integration
├── start_simple_demo.py         # Automated startup script
├── test_simple_integration.py   # Integration testing
├── requirements.txt             # Python dependencies
├── .gitignore                   # Git ignore file
└── README.md                    # This file

🧪 Testing

Test FastAPI Endpoints

# Start the server
python app.py

# In another terminal, test endpoints
curl http://localhost:8000/health
curl http://localhost:8000/users
curl http://localhost:8000/tasks

Test MCP Server

python simple_mcp_server.py

Test Gemini Integration

# Make sure FastAPI server is running
python app.py

# In another terminal, run integration
python simple_gemini_integration.py

Test Everything

python test_simple_integration.py

🔍 Troubleshooting

Common Issues

1. "Please set GEMINI_API_KEY environment variable"

   • Make sure you have a .env file with your API key
   • Check that the API key is valid

2. "Error connecting to MCP server"

   • Ensure the FastAPI server is running on port 8000
   • Check that all dependencies are installed

3. "ModuleNotFoundError"

   • Run pip install -r requirements.txt
   • Make sure you're using Python 3.8+

Debug Mode

To see more detailed error messages, you can modify the integration script to include more logging.

🚀 Next Steps

• Add more FastAPI endpoints
• Create additional MCP tools
• Implement authentication
• Add database persistence
• Create a web interface
• Deploy to cloud platforms

📚 Learn More

• FastAPI Documentation
• FastMCP Documentation
• Google Gemini API
• Model Context Protocol

🤝 Contributing

Feel free to submit issues and enhancement requests!

📄 License

This project is open source and available under the MIT License.