FastAPI + MCP Server Integration with Gemini CLI

This project demonstrates how to build a FastAPI application, wrap it as an MCP (Model Context Protocol) Server, and integrate it with Gemini CLI for direct tool calling.

Project Structure

├── sample_app.py      # FastAPI application with user and task management
├── mcp_server.py      # MCP server that wraps the FastAPI app
├── requirements.txt   # Python dependencies
├── setup.sh          # Setup script
├── demo.sh           # Interactive demonstration script
├── test_integration.py # Integration test script
├── venv/             # Python virtual environment
└── README.md         # This file

Features

FastAPI Application (sample_app.py)

• User Management: Create, read users with name, email, and age
• Task Management: Create, read, update, delete tasks
• Statistics: Get overview of users and tasks
• Health Check: Basic health monitoring endpoint

MCP Server (mcp_server.py)

• Tool Integration: Exposes all FastAPI endpoints as MCP tools
• Error Handling: Proper HTTP error handling and logging
• Type Safety: Full type annotations and schema validation

Available MCP Tools

1. get_app_info - Get basic app information
2. get_health - Check app health status
3. get_users - List all users
4. create_user - Create a new user
5. get_user - Get user by ID
6. get_tasks - List all tasks
7. create_task - Create a new task
8. get_task - Get task by ID
9. update_task - Update an existing task
10. delete_task - Delete a task
11. get_stats - Get user and task statistics

Quick Start

Option 1: Automated Demo

./demo.sh

This interactive script will guide you through the entire setup and testing process.

Option 2: Manual Setup

1. Run Setup Script

./setup.sh

2. Start the FastAPI Application

source venv/bin/activate
python sample_app.py

The FastAPI app will be available at http://localhost:8000

3. Start the MCP Server (in another terminal)

source venv/bin/activate
python mcp_server.py

4. Install Gemini CLI

npm install -g @google/gemini-cli@latest

5. Add MCP Server to Gemini CLI

gemini mcp add fastapi-sample stdio python $(pwd)/mcp_server.py

6. Test the Integration

# List available tools
gemini mcp list

# Call a tool
gemini call fastapi-sample get_app_info

# Create a user
gemini call fastapi-sample create_user --name "John Doe" --email "john@example.com" --age 30

# Get all users
gemini call fastapi-sample get_users

# Create a task
gemini call fastapi-sample create_task --title "Learn MCP" --description "Study Model Context Protocol" --user_id 1

# Get statistics
gemini call fastapi-sample get_stats

Manual Setup

If you prefer to set up manually:

1. Install Python Dependencies

pip3 install -r requirements.txt

2. Start Services

• FastAPI app: python3 sample_app.py
• MCP server: python3 mcp_server.py

3. Install and Configure Gemini CLI

npm install -g @google/gemini-cli@latest
gemini mcp add fastapi-sample stdio python3 /path/to/mcp_server.py

API Endpoints

The FastAPI application provides the following REST endpoints:

• GET / - App information
• GET /health - Health check
• GET /users - List users
• POST /users - Create user
• GET /users/{user_id} - Get user by ID
• GET /tasks - List tasks
• POST /tasks - Create task
• GET /tasks/{task_id} - Get task by ID
• PUT /tasks/{task_id} - Update task
• DELETE /tasks/{task_id} - Delete task
• GET /stats - Get statistics

MCP Tool Examples

Create and Manage Users

# Create a user
gemini call fastapi-sample create_user --name "Alice Smith" --email "alice@example.com" --age 25

# Get user by ID
gemini call fastapi-sample get_user --user_id 1

# List all users
gemini call fastapi-sample get_users

Create and Manage Tasks

# Create a task
gemini call fastapi-sample create_task --title "Complete project" --description "Finish the MCP integration" --user_id 1

# Update a task
gemini call fastapi-sample update_task --task_id 1 --title "Complete project" --description "Finish the MCP integration" --user_id 1 --completed true

# Delete a task
gemini call fastapi-sample delete_task --task_id 1

Get Statistics

gemini call fastapi-sample get_stats

Troubleshooting

Common Issues

1. Port already in use: Make sure port 8000 is available for the FastAPI app
2. MCP server connection failed: Ensure the FastAPI app is running before starting the MCP server
3. Gemini CLI not found: Make sure Node.js and npm are installed, then install Gemini CLI globally

Debug Mode

To run the FastAPI app in debug mode:

uvicorn sample_app:app --reload --host 0.0.0.0 --port 8000

Check MCP Server Status

gemini mcp list

Development

Adding New Endpoints

1. Add the endpoint to sample_app.py
2. Add the corresponding tool to mcp_server.py in the handle_list_tools() function
3. Add the tool handler in the handle_call_tool() function

Testing

You can test the FastAPI endpoints directly using curl:

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

# Create a user
curl -X POST http://localhost:8000/users \
  -H "Content-Type: application/json" \
  -d '{"name": "Test User", "email": "test@example.com", "age": 30}'

# Get users
curl http://localhost:8000/users

License

This project is for educational purposes and demonstrates MCP integration patterns.