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-generator3description: 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<!-- Generated from harness/github-copilot/skills/python-mcp-server-generator/SKILL.md by harness/claude-code/scripts/convert_from_copilot.py. Edit the source, not this file. -->78# Python MCP server generator910Create a production-ready Python MCP server project with `uv`, `mcp[cli]`, `FastMCP`, typed tools, validation, transport configuration, and runnable testing instructions.1112## When to invoke1314- "Generate a Python MCP server."15- "Create a FastMCP tool server with uv."16- "Scaffold an MCP server using streamable-http."17- "Add resources and prompts to a Python MCP server."18- "Build a typed MCP tool with error handling."1920## Project structure2122| File or element | Required | Purpose |23| --- | --- | --- |24| `pyproject.toml` | Yes | `uv init project-name` creates Python project metadata. |25| `mcp[cli]` dependency | Yes | `uv add "mcp[cli]"` installs the MCP SDK and CLI helpers. |26| `server.py` | Yes | Main server using `FastMCP` from `mcp.server.fastmcp`. |27| `.gitignore` | Yes | Python cache, virtualenv, build, and local env exclusions. |28| `if __name__ == "__main__"` | Yes | Allows direct execution. |29| README or usage notes | Yes | Shows run, inspect, and install commands. |3031## Setup commands3233```bash34uv init project-name35cd project-name36uv add "mcp[cli]"37```3839Create the server entry point, commonly `server.py`, and configure direct execution.4041## Server configuration4243| Choice | Recommendation |44| --- | --- |45| Server class | Use `FastMCP` from `mcp.server.fastmcp`. |46| Server name | Set a clear name and optional instructions. |47| Local transport | Use stdio by default for local desktop or CLI clients. |48| Remote transport | Use `streamable-http` for remote clients. |49| 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. |50| ASGI integration | Mount to existing Starlette or FastAPI apps when the server is part of a larger web service. |5152For HTTP testing, connect clients to `http://localhost:PORT/mcp`.5354## Tool implementation rules5556| Rule | Why |57| --- | --- |58| Decorate tools with `@mcp.tool()` | Registers callable MCP tools. |59| Type every parameter and return value | Type hints generate schemas automatically. |60| Write clear docstrings | Docstrings become tool descriptions. |61| Use Pydantic models or TypedDicts for structured output | Keeps responses schema-safe. |62| Use async functions for I/O-bound work | Avoids blocking the server. |63| Validate inputs early | Produces clear errors and safer tools. |64| Raise or return clear errors | Helps clients remediate failures. |65| Log to stderr or use Context logging | Avoids stdout pollution in stdio servers. |66| Clean up resources with context managers or lifespan hooks | Prevents leaked connections. |6768## Optional MCP capabilities6970| Capability | Decorator or API | Use when |71| --- | --- | --- |72| Resources | `@mcp.resource()` | Clients need read-only data exposed by URI. |73| Dynamic resources | URI templates such as `resource://{param}` | Resource identity depends on a parameter. |74| Prompts | `@mcp.prompt()` | Reusable prompt templates help clients invoke workflows. |75| Context | Context logging, progress, and notifications | Long-running or observable operations need status. |76| Sampling | LLM sampling | A tool intentionally delegates generation to a model. |77| Elicitation | User input elicitation | A workflow needs interactive user input. |78| Lifespan | Lifespan management | Shared databases, connections, or clients must be initialized and closed. |79| Image handling | `Image` class | Tools return or process images. |80| Completion | Completion support | Better UX for constrained or discoverable arguments. |8182## Tool ideas8384- Data processing and transformation.85- File system read, analyze, or search operations.86- External API integrations.87- Database queries.88- Text analysis or generation with sampling.89- System information retrieval.90- Math or scientific calculations.9192## Testing and installation9394| Scenario | Command |95| --- | --- |96| Run stdio server directly | `python server.py` or `uv run server.py` |97| Run MCP Inspector | `uv run mcp dev server.py` |98| Install to Claude Desktop | `uv run mcp install server.py` |99| Run HTTP server | `python server.py`, then connect to `http://localhost:PORT/mcp` |100101Test tools independently before relying on LLM integration. Include example tool invocations in the generated README.102103## Gotchas104105- **Type hints are not optional**: missing hints produce weak or missing schemas.106- **Do not print logs to stdout in stdio mode**: stdout is protocol traffic; use stderr or Context logging.107- **Do not make every operation sync**: I/O-bound APIs and databases should use async/await.108- **Do not skip cleanup**: shared clients and database connections need context managers or lifespan management.109110The 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`.111112## Output template113114```markdown115## Python MCP server generated116117**Status:** complete | blocked118**Project:** `<project-name>`119**Transport:** `stdio | streamable-http`120121### Files created122| File | Purpose |123| --- | --- |124| `pyproject.toml` | `<dependencies and metadata>` |125| `server.py` | `<FastMCP server and tools>` |126| `.gitignore` | `<Python ignores>` |127| `README.md` | `<run/test/install instructions>` |128129### Validation130- `uv run mcp dev server.py`: `<pass/fail/not run>`131- Direct run: `<pass/fail/not run>`132- Example tool invocation: `<pass/fail/not run>`133```134135## Quality gate136137- [ ] Project was initialized with `uv init project-name` or equivalent `uv` structure.138- [ ] `mcp[cli]` was added with `uv add "mcp[cli]"`.139- [ ] Server uses `FastMCP` from `mcp.server.fastmcp`.140- [ ] Transport is explicitly stdio or `streamable-http`.141- [ ] At least one useful `@mcp.tool()` has type hints, docstring, validation, and error handling.142- [ ] Optional `@mcp.resource()` and `@mcp.prompt()` are included only when useful.143- [ ] Structured outputs use Pydantic models or TypedDicts when appropriate.144- [ ] Logs avoid stdout pollution in stdio mode.145- [ ] README or final notes include `uv run mcp dev server.py`, `uv run mcp install server.py`, and direct run instructions.
paulasilvatech