| name | python-mcp-server-generator |
| description | Generate a complete, production-ready MCP server project in Python (FastMCP) with typed tools, resources, prompts, and proper configuration. Use when scaffolding a new MCP server from scratch, bootstrapping an MCP project with uv, or generating tool/resource/prompt boilerplate that follows MCP best practices. |
| license | Proprietary |
| compatibility | Requires Python 3.10+ and uv |
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
.gitignore for Python projects
- Configure for direct execution with
if __name__ == "__main__"
Server Configuration
- Use
FastMCP class from mcp.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.
