CarstenMaul/mcp-server-fastapi

MCP Quote Server with FastAPI

A Model Context Protocol (MCP) server built with FastAPI that provides quote of the day functionality with comprehensive logging and HTTPS support.

Features

• MCP Protocol Support: Full implementation of Model Context Protocol
• Quote Management: Random quote selection and daily quote feature
• Comprehensive Logging: Full HTTP request/response logging with detailed headers and bodies
• HTTPS Support: Built-in SSL/TLS support for secure connections
• Production Ready: Includes systemd service configuration for Ubuntu deployment

MCP Tools Available

• get_quote: Get a random quote from the collection
• get_all_quotes: List all available quotes

MCP Resources Available

• quote://daily: Get the quote of the day (deterministic based on date)

Local Development

Prerequisites

• Python 3.8+
• Virtual environment (optional but recommended)

Setup

1. Clone the repository:

git clone https://github.com/your-username/mcp-server-fastapi.git
cd mcp-server-fastapi

2. Create and activate virtual environment:

python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies:

pip install -r requirements.txt

4. Create logs directory:

mkdir logs

Running Locally

For development (HTTP):

python server.py --dev

For production mode with HTTPS (requires SSL certificates):

# Place certificates in ssl/ directory
mkdir ssl
cp /path/to/fullchain.pem ssl/
cp /path/to/privkey.pem ssl/
python server.py

The server will run on port 8000.

Production Deployment on Ubuntu

Quick Deploy

1. SSH to your Ubuntu server:

ssh user@server

2. Clone the repository and run deployment:

cd /opt
sudo git clone https://github.com/CarstenMaul/mcp-server-fastapi.git
cd mcp-server-fastapi
sudo bash deploy.sh

Manual Deployment

1. Install system dependencies:

sudo apt update
sudo apt install python3 python3-pip python3-venv git

2. Create service user:

sudo useradd -r -s /bin/false mcp-server-fastapi

3. Clone repository:

cd /opt
sudo git clone https://github.com/CarstenMaul/mcp-server-fastapi.git
cd mcp-server-fastapi

4. Create required directories:

sudo mkdir -p /opt/mcp-server-fastapi/ssl
sudo mkdir -p /opt/mcp-server-fastapi/logs

5. Set up Python environment:

cd /opt/mcp-server-fastapi
sudo python3 -m venv venv
sudo venv/bin/pip install -r requirements.txt

6. Add SSL certificates:

sudo cp /path/to/fullchain.pem /opt/mcp-server-fastapi/ssl/
sudo cp /path/to/privkey.pem /opt/mcp-server-fastapi/ssl/
sudo chmod 600 /opt/mcp-server-fastapi/ssl/*.pem

7. Set permissions:

sudo chown -R mcp-server-fastapi:mcp-server-fastapi /opt/mcp-server-fastapi

8. Install systemd service:

sudo cp /opt/mcp-server-fastapi/mcp-server-fastapi.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable mcp-server-fastapi
sudo systemctl start mcp-server-fastapi

9. Configure firewall:

sudo ufw allow 8000/tcp

Service Management

Check status:

sudo systemctl status mcp-server-fastapi

View logs:

# Service logs
sudo journalctl -u mcp-server-fastapi -f

# Application logs
sudo tail -f /opt/mcp-server-fastapi/logs/mcp-server.log

Restart service:

sudo systemctl restart mcp-server-fastapi

SSL Certificate Setup

Using Let's Encrypt (Recommended for production)

sudo apt install certbot
sudo certbot certonly --standalone -d your-domain.com
sudo cp /etc/letsencrypt/live/your-domain.com/fullchain.pem /opt/mcp-server-fastapi/ssl/
sudo cp /etc/letsencrypt/live/your-domain.com/privkey.pem /opt/mcp-server-fastapi/ssl/
sudo chown mcp-server-fastapi:mcp-server-fastapi /opt/mcp-server-fastapi/ssl/*.pem
sudo chmod 600 /opt/mcp-server-fastapi/ssl/*.pem
sudo systemctl restart mcp-server-fastapi

Using Self-Signed Certificates (For testing)

openssl req -x509 -newkey rsa:4096 -keyout privkey.pem -out fullchain.pem -days 365 -nodes

Testing the MCP Server

Test basic connectivity:

curl https://localhost:8000/

Test MCP initialize:

curl -X POST https://localhost:8000/ \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {}}'

Test getting a quote:

curl -X POST https://localhost:8000/ \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "get_quote"}}'

Logs

The server provides comprehensive logging:

• Application logs: logs/mcp-server.log - Contains all HTTP requests/responses with full details
• Service logs: /opt/mcp-server-fastapi/logs/service.log (in production)
• Error logs: /opt/mcp-server-fastapi/logs/service-error.log (in production)

Log format includes:

• Request ID for tracking
• Full HTTP headers
• Complete request/response bodies
• Processing time
• Error details

Configuration

The server runs on port 8000 by default and can be configured to use:

• HTTP mode for development (--dev flag)
• HTTPS mode for production (automatic when SSL certificates are present)

Security Notes

• The service runs as a non-privileged user in production
• SSL/TLS is enforced when certificates are available
• Comprehensive logging helps with security auditing
• CORS is configured to allow all origins (adjust as needed for production)

Troubleshooting

Service won't start

• Check logs: sudo journalctl -u mcp-server-fastapi -n 50
• Verify SSL certificates exist and have correct permissions
• Ensure port 8000 is not already in use

SSL certificate issues

• Verify certificate files exist in /opt/mcp-server-fastapi/ssl/
• Check permissions: should be owned by mcp-server-fastapi user with 600 permissions
• Ensure fullchain.pem and privkey.pem are valid PEM format

Permission denied errors

• Ensure mcp-server-fastapi user owns all files in /opt/mcp-server-fastapi/
• Check that logs directory is writable

License

MIT