Generate Python MCP Server
Create a complete Model Context Protocol (MCP) server in Python with the following specifications:
Requirements
- Project Structure: Create a new Python project with proper structure using uv
- Dependencies: Include mcp[cli] package with uv
- Transport Type: Choose between stdio (for local) or streamable-http (for remote)
- Tools: Create at least one useful tool with proper type hints
- Error Handling: Include comprehensive error handling and validation
Implementation Details
Project Setup
- Initialize with
uv init project-name - Add MCP SDK:
uv add "mcp[cli]" - Create main server file (e.g.,
server.py) - Add
.gitignorefor Python projects - Configure for direct execution with
if __name__ == "__main__"
Server Configuration
- Use
FastMCPclass frommcp.server.fastmcp - Set server name and optional instructions
- Choose transport: stdio (default) or streamable-http
- For HTTP: optionally configure host, port, and stateless mode
Tool Implementation
- Use
@mcp.tool()decorator on functions - Always include type hints - they generate schemas automatically
- Write clear docstrings - they become tool descriptions
- Use Pydantic models or TypedDicts for structured outputs
- Support async operations for I/O-bound tasks
- Include proper error handling
Resource/Prompt Setup (Optional)
- Add resources with
@mcp.resource()decorator - Use URI templates for dynamic resources:
"resource://{param}" - Add prompts with
@mcp.prompt()decorator - Return strings or Message lists from prompts
Code Quality
- Use type hints for all function parameters and returns
- Write docstrings for tools, resources, and prompts
- Follow PEP 8 style guidelines
- Use async/await for asynchronous operations
- Implement context managers for resource cleanup
- Add inline comments for complex logic
Example Tool Types to Consider
- Data processing and transformation
- File system operations (read, analyze, search)
- External API integrations
- Database queries
- Text analysis or generation (with sampling)
- System information retrieval
- Math or scientific calculations
Configuration Options
- For stdio Servers:
- Simple direct execution - Test with uv run mcp dev server.py - Install to Claude: uv run mcp install server.py
- For HTTP Servers:
- Port configuration via environment variables - Stateless mode for scalability: stateless_http=True - JSON response mode: json_response=True - CORS configuration for browser clients - Mounting to existing ASGI servers (Starlette/FastAPI)
Testing Guidance
- Explain how to run the server:
- stdio: python server.py or uv run server.py - HTTP: python server.py then connect to http://localhost:PORT/mcp
- Test with MCP Inspector:
uv run mcp dev server.py - Install to Claude Desktop:
uv run mcp install server.py - Include example tool invocations
- Add troubleshooting tips
Additional Features to Consider
- Context usage for logging, progress, and notifications
- LLM sampling for AI-powered tools
- User input elicitation for interactive workflows
- Lifespan management for shared resources (databases, connections)
- Structured output with Pydantic models
- Icons for UI display
- Image handling with Image class
- Completion support for better UX
Best Practices
- Use type hints everywhere - they're not optional
- Return structured data when possible
- Log to stderr (or use Context logging) to avoid stdout pollution
- Clean up resources properly
- Validate inputs early
- Provide clear error messages
- Test tools independently before LLM integration
Generate a complete, production-ready MCP server with type safety, proper error handling, and comprehensive documentation.