Python MCP Server 🚀

Introduction

This is a secure, production-ready server implementing the Model Context Protocol (MCP) with Server-Sent Events (SSE). It provides a comprehensive example of how to build, secure, and test an MCP server with proper security practices.

🔧 Features

Weather Tool: Get current weather for any city using wttr.in API
Math Tool: Simple addition functionality
Secret Word Tool: Generate random words
Security Hardened: Comprehensive security testing and validation
Production Ready: Docker support and proper error handling

🚀 Quick Start

1. Set up your Python environment

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

2. Install the required packages

pip install -r requirements.txt

3. Start the server safely

# Use the safe startup script (recommended)
./start_server.sh

# Or start manually
python server.py

The server will start on http://localhost:8080 by default.

🧪 Testing & Security

Security Status: ✅ SECURE

This server has been comprehensively tested for security vulnerabilities and is production-ready.

Run Security Tests

# Basic security test (recommended)
python3 simple_test.py

# Comprehensive MCP protocol test
python3 test_client.py

# Advanced security analysis
python3 security_test.py

Security Features ✅

Input Validation: All malicious payloads are properly rejected
Endpoint Protection: Undefined endpoints return 404
Protocol Enforcement: MCP protocol properly enforced
External API Security: Safe integration with weather API
Error Handling: Graceful error handling and logging

🔒 Important Security Notes

⚠️ Why Simple HTTP Requests Don't Work

DON'T DO THIS:

# ❌ This will NOT work - MCP is not a REST API
curl http://localhost:8080/tool/get_current_weather?city=Amsterdam

DO THIS INSTEAD: Use proper MCP clients (like Cursor, Claude Desktop) that implement the JSON-RPC 2.0 protocol.

MCP Protocol Requirements

MCP tools require:

JSON-RPC 2.0 protocol
Proper session management
Structured message format
MCP-compatible client

🌐 Usage in MCP Clients

Cursor IDE

Add to your mcp.json file:

{
  "demo-mcp": {
    "url": "https://your-domain.com/sse"
  }
}

Claude Desktop

Add to your MCP configuration:

{
  "mcpServers": {
    "demo-mcp": {
      "url": "https://your-domain.com/sse"
    }
  }
}

Important: Replace your-domain.com with your actual server domain and use HTTPS in production.

🐳 Docker Deployment

Build and Run

# Build the container
docker build -t mcp-server .

# Run the container
docker run -p 8080:8080 mcp-server

Production Environment

For deployment on cloud platforms, make sure to:

Use HTTPS (not HTTP)
Set proper environment variables
Enable logging and monitoring
Use the provided Dockerfile

📁 Project Structure

├── server.py              # Main MCP server implementation
├── requirements.txt       # Python dependencies
├── Dockerfile            # Container configuration
├── start_server.sh       # Safe server startup script
├── simple_test.py        # Basic security testing
├── test_client.py        # MCP protocol testing
├── security_test.py      # Advanced security analysis
├── SECURITY_TESTING.md   # Detailed security documentation
└── README.md            # This file

🛠️ Available Tools

1. Weather Tool

get_current_weather(city: str) -> str

Get current weather information for any city.

2. Math Tool

add(a: int, b: int) -> int

Add two numbers together.

3. Secret Word Tool

get_secret_word() -> str

Get a random secret word.

🔧 Development

Server Management

# Start server
./start_server.sh

# Stop server
pkill -f "python3 server.py"

# Check server status
ps aux | grep "python3 server.py"

Testing During Development

# Quick security check
python3 simple_test.py

# Full protocol test
python3 test_client.py

🛡️ Security Recommendations

For Production

Use HTTPS: Never use HTTP in production
Add Security Headers: Implement recommended HTTP security headers
Monitor Logs: Set up proper logging and monitoring
Rate Limiting: Consider implementing rate limiting
Keep Updated: Regularly update dependencies

Security Headers (Recommended)

# Add these headers in production
"X-Content-Type-Options": "nosniff"
"X-Frame-Options": "DENY"
"X-XSS-Protection": "1; mode=block"
"Strict-Transport-Security": "max-age=31536000"

📊 Test Results Summary

Test Category	Status	Details
Server Access	✅ Pass	Server responds correctly
Endpoint Security	✅ Pass	All undefined endpoints blocked
Input Validation	✅ Pass	Malicious inputs rejected
Protocol Security	✅ Pass	MCP protocol enforced
External APIs	✅ Pass	Weather API works securely
Headers	⚠️ Warning	Security headers recommended

🆘 Troubleshooting

Common Issues

"TypeError: FastMCP.init() got an unexpected keyword argument 'logger'"
- Solution 5F05 : Already fixed in this version. The server uses log_level instead of logger.
"No data found or available" when accessing tools via HTTP
- Cause: MCP is not a REST API
- Solution: Use proper MCP clients, not direct HTTP requests
SSE endpoint timeout
- Cause: Normal behavior for streaming endpoints
- Solution: Use MCP clients that handle SSE properly

Getting Help

Check SECURITY_TESTING.md for detailed security information
Run python3 simple_test.py to verify server status
Ensure virtual environment is activated
Check server logs for detailed error information

📝 License

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

🤝 Contributing

Fork the repository
Create a feature branch
Run security tests: python3 simple_test.py
Submit a pull request

⚠️ Security Notice: This server has been tested for common security vulnerabilities and is considered secure for production use. Always use HTTPS in production environments.

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
.dockerignore		.dockerignore
.gitignore		.gitignore
Dockerfile		Dockerfile
README.md		README.md
SECURITY_TESTING.md		SECURITY_TESTING.md
requirements.txt		requirements.txt
security_test.py		security_test.py
server.py		server.py
simple_test.py		simple_test.py
start_server.sh		start_server.sh
test_client.py		test_client.py

Brave-Python/python-mcp-server

Folders and files

Latest commit

History

Repository files navigation