Fast MCP Server with Google Gemini Integration
A comprehensive Model Context Protocol (MCP) server built with FastAPI that integrates with Google Gemini CLI for AI-powered task management and data processing.
🚀 Features
- FastAPI-based MCP Server: High-performance async server running on port 5000
- Google Gemini Integration: Seamless integration with Gemini CLI for AI responses
- Task Management Tools: Complete CRUD operations for task management
- Data Analytics: Task statistics and CSV export capabilities
- Comprehensive Logging: JSON-based operation logging for tracking and debugging
- CLI Interface: Easy-to-use command-line tool for server interaction
- RESTful API: Full API documentation with Swagger UI
- Production Ready: Modular, clean, and well-documented code
📋 Prerequisites
- Python 3.8 or higher
- Google Gemini CLI installed and configured
- curl (for CLI operations)
- Git (for cloning the repository)
🛠️ Installation
1. Clone the Repository
git clone <repository-url>
cd FAST_MCP
2. Create Virtual Environment
python3 -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
3. Install Dependencies
pip install -r requirements.txt
4. Install Google Gemini CLI
Follow the official Gemini CLI installation guide:
Make sure Gemini CLI is properly configured with your API key.
🚀 Quick Start
Start the Server
./mcp_cli.sh start
The server will start on http://localhost:5000
Check Server Status
./mcp_cli.sh status
List Available Tools
./mcp_cli.sh list
Use MCP Tools
# List all tasks
./mcp_cli.sh run list_tasks
# Create a new task
./mcp_cli.sh run create_task "Implement authentication" "Add JWT-based auth" "high"
# Update task status
./mcp_cli.sh run update_task_status 1 "in_progress"
# Search tasks
./mcp_cli.sh run search_tasks "authentication"
# Get task statistics
./mcp_cli.sh run get_task_statistics
# Export tasks to CSV
./mcp_cli.sh run export_tasks_to_csv
Interact with Gemini
./mcp_cli.sh gemini "What are the best practices for API security?"
View Logs
./mcp_cli.sh logs
Stop the Server
./mcp_cli.sh stop
📚 API Documentation
Once the server is running, visit:
- Swagger UI: http://localhost:5000/docs
- ReDoc: http://localhost:5000/redoc
🔧 Available MCP Tools
1. list_tasks
- Description: List all tasks with optional status filtering
- Parameters:
status_filter(optional): Filter by status (pending, in_progress, completed)
- Example:
./mcp_cli.sh run list_tasks pending
2. create_task
- Description: Create a new task
- Parameters:
title(required): Task titledescription(required): Task descriptionpriority(optional): Priority level (low, medium, high)assigned_to(optional): User ID to assign the task
- Example:
./mcp_cli.sh run create_task "New Feature" "Implement user dashboard" "high" "dev1"
3. update_task_status
- Description: Update the status of an existing task
- Parameters:
task_id(required): ID of the task to updatenew_status(required): New status (pending, in_progress, completed)
- Example:
./mcp_cli.sh run update_task_status 1 "completed"
4. get_task_statistics
- Description: Get comprehensive task statistics and analytics
- Parameters: None
- Example:
./mcp_cli.sh run get_task_statistics
5. search_tasks
- Description: Search tasks by title or description
- Parameters:
query(required): Search query string
- Example:
./mcp_cli.sh run search_tasks "authentication"
6. export_tasks_to_csv
- Description: Export all tasks to a CSV file
- Parameters: None
- Example:
./mcp_cli.sh run export_tasks_to_csv
🤖 Gemini Integration
The server integrates with Google Gemini CLI to provide AI-powered responses:
Features
- Multi-turn Conversations: Maintains context across interactions
- Error Handling: Graceful handling of CLI failures and timeouts
- Logging: All Gemini interactions are logged for tracking
- Timeout Protection: 30-second timeout to prevent hanging requests
Usage Examples
# Technical questions
./mcp_cli.sh gemini "How do I implement JWT authentication in FastAPI?"
# Code review
./mcp_cli.sh gemini "Review this Python function for best practices"
# Documentation help
./mcp_cli.sh gemini "Generate API documentation for a task management system"
📁 Project Structure
FAST_MCP/
├── server.py # Main FastAPI server
├── requirements.txt # Python dependencies
├── mcp_cli.sh # CLI interface script
├── sample_data.json # Sample task data
├── README.md # This file
├── venv/ # Virtual environment (created during setup)
├── server.log # Server logs (created when running)
├── mcp_logs.json # MCP operation logs (created when running)
└── tasks_export_*.csv # Exported CSV files (created when exporting)
🔍 Logging and Monitoring
Operation Logs
All MCP tool calls and Gemini interactions are logged to mcp_logs.json:
{
"timestamp": "2024-01-17T10:30:00Z",
"operation": "mcp_tool_call",
"tool_name": "create_task",
"success": true,
"result": {...},
"error": null
}
Server Logs
Server logs are written to server.log and include:
- Server startup/shutdown events
- Request/response details
- Error messages and stack traces
- Performance metrics
Health Monitoring
Check server health at any time:
./mcp_cli.sh health
🛡️ Error Handling
The server includes comprehensive error handling:
- Tool Validation: Validates tool names and parameters
- Data Persistence: Handles file I/O errors gracefully
- Gemini CLI Integration: Manages CLI failures and timeouts
- HTTP Errors: Proper HTTP status codes and error messages
- Logging: All errors are logged for debugging
🔧 Configuration
Server Configuration
- Port: 5000 (configurable in
server.py) - Host: 0.0.0.0 (all interfaces)
- Data File:
sample_data.json - Log File:
mcp_logs.json
Gemini CLI Configuration
Ensure Gemini CLI is properly configured:
gemini config set api_key YOUR_API_KEY
🚀 Deployment
Development
./mcp_cli.sh start
Production
For production deployment, consider:
- Using a process manager like PM2 or systemd
- Setting up reverse proxy with Nginx
- Implementing proper authentication
- Adding rate limiting
- Setting up monitoring and alerting
🧪 Testing
Manual Testing
- Start the server:
./mcp_cli.sh start - Test each tool:
./mcp_cli.sh run <tool_name> - Test Gemini integration:
./mcp_cli.sh gemini "test prompt" - Check logs:
./mcp_cli.sh logs - Verify health:
./mcp_cli.sh health
API Testing
Use the Swagger UI at http://localhost:5000/docs to test API endpoints directly.
📊 Sample Data
The project includes sample_data.json with:
- 5 sample tasks with different statuses and priorities
- 4 user profiles with roles and departments
- 2 project definitions with team assignments
🤝 Contributing
- Fork the repository
- Create a feature branch:
git checkout -b feature-name - Make your changes
- Test thoroughly
- Commit your changes:
git commit -m "Add feature" - Push to the branch:
git push origin feature-name - Submit a pull request
📝 License
This project is licensed under the MIT License - see the LICENSE file for details.
🆘 Troubleshooting
Common Issues
-
Server won't start
- Check if port 5000 is available
- Verify virtual environment is activated
- Check
server.logfor error details
-
Gemini CLI not found
- Install Gemini CLI:
pip install google-generativeai - Configure API key:
gemini config set api_key YOUR_KEY
- Install Gemini CLI:
-
Permission denied on mcp_cli.sh
- Make executable:
chmod +x mcp_cli.sh
- Make executable:
-
Data file errors
- Check file permissions
- Verify JSON format in
sample_data.json
Getting Help
- Check the logs:
./mcp_cli.sh logs - Review server logs:
tail -f server.log - Test server health:
./mcp_cli.sh health - Check API documentation: http://localhost:5000/docs
🎯 Roadmap
- Add user authentication and authorization
- Implement real-time notifications
- Add more MCP tools (file processing, email, etc.)
- Create web dashboard
- Add unit and integration tests
- Implement caching for better performance
- Add Docker support
- Create CI/CD pipeline
📞 Support
For support and questions:
- Create an issue in the repository
- Check the troubleshooting section
- Review the API documentation
Built with ❤️ using FastAPI and Google Gemini