Python MCP server generator
Create a production-ready Python MCP server project with uv, mcp[cli], FastMCP, typed tools, validation, transport configuration, and runnable testing instructions.
When to invoke
- "Generate a Python MCP server."
- "Create a FastMCP tool server with uv."
- "Scaffold an MCP server using streamable-http."
- "Add resources and prompts to a Python MCP server."
- "Build a typed MCP tool with error handling."
Project structure
| File or element |
Required |
Purpose |
pyproject.toml |
Yes |
uv init project-name creates Python project metadata. |
mcp[cli] dependency |
Yes |
uv add "mcp[cli]" installs the MCP SDK and CLI helpers. |
server.py |
Yes |
Main server using FastMCP from mcp.server.fastmcp. |
.gitignore |
Yes |
Python cache, virtualenv, build, and local env exclusions. |
if __name__ == "__main__" |
Yes |
Allows direct execution. |
| README or usage notes |
Yes |
Shows run, inspect, and install commands. |
Setup commands
uv init project-name
cd project-name
uv add "mcp[cli]"
Create the server entry point, commonly server.py, and configure direct execution.
Server configuration
| Choice |
Recommendation |
| Server class |
Use FastMCP from mcp.server.fastmcp. |
| Server name |
Set a clear name and optional instructions. |
| Local transport |
Use stdio by default for local desktop or CLI clients. |
| Remote transport |
Use streamable-http for remote clients. |
| HTTP options |
Configure host, port, stateless_http=True for scalability, json_response=True when JSON responses are required, and CORS only for trusted browser clients. |
| ASGI integration |
Mount to existing Starlette or FastAPI apps when the server is part of a larger web service. |
For HTTP testing, connect clients to http://localhost:PORT/mcp.
Tool implementation rules
| Rule |
Why |
Decorate tools with @mcp.tool() |
Registers callable MCP tools. |
| Type every parameter and return value |
Type hints generate schemas automatically. |
| Write clear docstrings |
Docstrings become tool descriptions. |
| Use Pydantic models or TypedDicts for structured output |
Keeps responses schema-safe. |
| Use async functions for I/O-bound work |
Avoids blocking the server. |
| Validate inputs early |
Produces clear errors and safer tools. |
| Raise or return clear errors |
Helps clients remediate failures. |
| Log to stderr or use Context logging |
Avoids stdout pollution in stdio servers. |
| Clean up resources with context managers or lifespan hooks |
Prevents leaked connections. |
Optional MCP capabilities
| Capability |
Decorator or API |
Use when |
| Resources |
@mcp.resource() |
Clients need read-only data exposed by URI. |
| Dynamic resources |
URI templates such as resource://{param} |
Resource identity depends on a parameter. |
| Prompts |
@mcp.prompt() |
Reusable prompt templates help clients invoke workflows. |
| Context |
Context logging, progress, and notifications |
Long-running or observable operations need status. |
| Sampling |
LLM sampling |
A tool intentionally delegates generation to a model. |
| Elicitation |
User input elicitation |
A workflow needs interactive user input. |
| Lifespan |
Lifespan management |
Shared databases, connections, or clients must be initialized and closed. |
| Image handling |
Image class |
Tools return or process images. |
| Completion |
Completion support |
Better UX for constrained or discoverable arguments. |
Tool ideas
- Data processing and transformation.
- File system read, analyze, or search operations.
- External API integrations.
- Database queries.
- Text analysis or generation with sampling.
- System information retrieval.
- Math or scientific calculations.
Testing and installation
| Scenario |
Command |
| Run stdio server directly |
python server.py or uv run server.py |
| Run MCP Inspector |
uv run mcp dev server.py |
| Install to Claude Desktop |
uv run mcp install server.py |
| Run HTTP server |
python server.py, then connect to http://localhost:PORT/mcp |
Test tools independently before relying on LLM integration. Include example tool invocations in the generated README.
Gotchas
- Type hints are not optional: missing hints produce weak or missing schemas.
- Do not print logs to stdout in stdio mode: stdout is protocol traffic; use stderr or Context logging.
- Do not make every operation sync: I/O-bound APIs and databases should use async/await.
- Do not skip cleanup: shared clients and database connections need context managers or lifespan management.
The optional Resource/Prompt section can use URI templates like "resource://{param}". HTTP servers can mount into Starlette/FastAPI; I/O code should use async/await.
Output template
## Python MCP server generated
**Status:** complete | blocked
**Project:** `<project-name>`
**Transport:** `stdio | streamable-http`
### Files created
| File | Purpose |
| --- | --- |
| `pyproject.toml` | `<dependencies and metadata>` |
| `server.py` | `<FastMCP server and tools>` |
| `.gitignore` | `<Python ignores>` |
| `README.md` | `<run/test/install instructions>` |
### Validation
- `uv run mcp dev server.py`: `<pass/fail/not run>`
- Direct run: `<pass/fail/not run>`
- Example tool invocation: `<pass/fail/not run>`
Quality gate
1---2name: python-mcp-server-generator-23description: Generate a complete Python Model Context Protocol server project using uv, mcp[cli], FastMCP, typed tools, optional resources and prompts, stdio or streamable-http transport, error handling, and testing instructions. Use when the user asks to generate a Python MCP server, create an MCP tool server, scaffold FastMCP, or build a streamable HTTP MCP service.4---56# Python MCP server generator78Create a production-ready Python MCP server project with `uv`, `mcp[cli]`, `FastMCP`, typed tools, validation, transport configuration, and runnable testing instructions.910## When to invoke1112- "Generate a Python MCP server."13- "Create a FastMCP tool server with uv."14- "Scaffold an MCP server using streamable-http."15- "Add resources and prompts to a Python MCP server."16- "Build a typed MCP tool with error handling."1718## Project structure1920| File or element | Required | Purpose |21| --- | --- | --- |22| `pyproject.toml` | Yes | `uv init project-name` creates Python project metadata. |23| `mcp[cli]` dependency | Yes | `uv add "mcp[cli]"` installs the MCP SDK and CLI helpers. |24| `server.py` | Yes | Main server using `FastMCP` from `mcp.server.fastmcp`. |25| `.gitignore` | Yes | Python cache, virtualenv, build, and local env exclusions. |26| `if __name__ == "__main__"` | Yes | Allows direct execution. |27| README or usage notes | Yes | Shows run, inspect, and install commands. |2829## Setup commands3031```bash32uv init project-name33cd project-name34uv add "mcp[cli]"35```3637Create the server entry point, commonly `server.py`, and configure direct execution.3839## Server configuration4041| Choice | Recommendation |42| --- | --- |43| Server class | Use `FastMCP` from `mcp.server.fastmcp`. |44| Server name | Set a clear name and optional instructions. |45| Local transport | Use stdio by default for local desktop or CLI clients. |46| Remote transport | Use `streamable-http` for remote clients. |47| HTTP options | Configure host, port, `stateless_http=True` for scalability, `json_response=True` when JSON responses are required, and CORS only for trusted browser clients. |48| ASGI integration | Mount to existing Starlette or FastAPI apps when the server is part of a larger web service. |4950For HTTP testing, connect clients to `http://localhost:PORT/mcp`.5152## Tool implementation rules5354| Rule | Why |55| --- | --- |56| Decorate tools with `@mcp.tool()` | Registers callable MCP tools. |57| Type every parameter and return value | Type hints generate schemas automatically. |58| Write clear docstrings | Docstrings become tool descriptions. |59| Use Pydantic models or TypedDicts for structured output | Keeps responses schema-safe. |60| Use async functions for I/O-bound work | Avoids blocking the server. |61| Validate inputs early | Produces clear errors and safer tools. |62| Raise or return clear errors | Helps clients remediate failures. |63| Log to stderr or use Context logging | Avoids stdout pollution in stdio servers. |64| Clean up resources with context managers or lifespan hooks | Prevents leaked connections. |6566## Optional MCP capabilities6768| Capability | Decorator or API | Use when |69| --- | --- | --- |70| Resources | `@mcp.resource()` | Clients need read-only data exposed by URI. |71| Dynamic resources | URI templates such as `resource://{param}` | Resource identity depends on a parameter. |72| Prompts | `@mcp.prompt()` | Reusable prompt templates help clients invoke workflows. |73| Context | Context logging, progress, and notifications | Long-running or observable operations need status. |74| Sampling | LLM sampling | A tool intentionally delegates generation to a model. |75| Elicitation | User input elicitation | A workflow needs interactive user input. |76| Lifespan | Lifespan management | Shared databases, connections, or clients must be initialized and closed. |77| Image handling | `Image` class | Tools return or process images. |78| Completion | Completion support | Better UX for constrained or discoverable arguments. |7980## Tool ideas8182- Data processing and transformation.83- File system read, analyze, or search operations.84- External API integrations.85- Database queries.86- Text analysis or generation with sampling.87- System information retrieval.88- Math or scientific calculations.8990## Testing and installation9192| Scenario | Command |93| --- | --- |94| Run stdio server directly | `python server.py` or `uv run server.py` |95| Run MCP Inspector | `uv run mcp dev server.py` |96| Install to Claude Desktop | `uv run mcp install server.py` |97| Run HTTP server | `python server.py`, then connect to `http://localhost:PORT/mcp` |9899Test tools independently before relying on LLM integration. Include example tool invocations in the generated README.100101## Gotchas102103- **Type hints are not optional**: missing hints produce weak or missing schemas.104- **Do not print logs to stdout in stdio mode**: stdout is protocol traffic; use stderr or Context logging.105- **Do not make every operation sync**: I/O-bound APIs and databases should use async/await.106- **Do not skip cleanup**: shared clients and database connections need context managers or lifespan management.107108The optional `Resource/Prompt` section can use URI templates like `"resource://{param}"`. HTTP servers can mount into `Starlette/FastAPI`; I/O code should use `async/await`.109110## Output template111112```markdown113## Python MCP server generated114115**Status:** complete | blocked116**Project:** `<project-name>`117**Transport:** `stdio | streamable-http`118119### Files created120| File | Purpose |121| --- | --- |122| `pyproject.toml` | `<dependencies and metadata>` |123| `server.py` | `<FastMCP server and tools>` |124| `.gitignore` | `<Python ignores>` |125| `README.md` | `<run/test/install instructions>` |126127### Validation128- `uv run mcp dev server.py`: `<pass/fail/not run>`129- Direct run: `<pass/fail/not run>`130- Example tool invocation: `<pass/fail/not run>`131```132133## Quality gate134135- [ ] Project was initialized with `uv init project-name` or equivalent `uv` structure.136- [ ] `mcp[cli]` was added with `uv add "mcp[cli]"`.137- [ ] Server uses `FastMCP` from `mcp.server.fastmcp`.138- [ ] Transport is explicitly stdio or `streamable-http`.139- [ ] At least one useful `@mcp.tool()` has type hints, docstring, validation, and error handling.140- [ ] Optional `@mcp.resource()` and `@mcp.prompt()` are included only when useful.141- [ ] Structured outputs use Pydantic models or TypedDicts when appropriate.142- [ ] Logs avoid stdout pollution in stdio mode.143- [ ] README or final notes include `uv run mcp dev server.py`, `uv run mcp install server.py`, and direct run instructions.
paulasilvatech