Python Mcp Template

A minimal FastMCP server scaffold for building your own MCP tools and resources. It includes typed examples, stderr-only logging, and a clean project layout that works with uv.

What's included

• FastMCP wiring in src/mcp_server/main.py.
• Typed models in src/mcp_server/models.py.
• Example tools: analyze_metrics (typed Pydantic input/output) and echo.
• A sample resource at template://config/defaults.
• Logging configured to use stderr only (safe for stdio transports).

Prerequisites

• Python 3.12+
• uv for dependency management and execution.

Setup and run

uv sync
uv run src/mcp_server/main.py   # or: uv run mcp-template

Try it with the MCP Inspector

Inspect tools and resources without an LLM in the loop:

npx @modelcontextprotocol/inspector uv run --directory . src/mcp_server/main.py

Extending the template

• Add new models to src/mcp_server/models.py (or a new module) with full type hints.
• Implement tool logic under src/mcp_server/tools/.
• Register tools/resources in src/mcp_server/main.py using the @mcp.tool() and @mcp.resource() decorators.
• Keep logging directed to stderr (see src/mcp_server/utils/logger.py) so stdio transports stay clean.

Tests and linting

uv run pytest
uv run ruff check .