mcp -python-template

This MCP server template provides a ready-to-use Python implementation for the Model Context Protocol (MCP). It includes an example weather service and embedded MCP documentation to help AI tools understand MCP concepts, transports, and namespaces. By default, the server runs over the stdio transport, which is ideal for CLI tooling and local development; it can also be extended to support SSE transport for web-based clients in the future. The included FastMCP setup demonstrates how to declare tools and expose them to MCP clients, enabling AI models to call external tools and retrieve data from external sources through a standardized interface.

To use it, install dependencies and run the server. The template shows how to define tools using the @mcp.tool() decorator and how to start the server with a specific transport. The weather example illustrates a realistic use case: exposing tools that fetch data from external services (e.g., the NWS API) and return results to clients. The embedded documentation in protocals (mcp.md and sdk.md) helps tools interpret MCP semantics without leaving the repository.

Prerequisites:

• Python 3.12+ (as required by the template)
• Basic development environment (git, Python, pip)

Step-by-step installation:

1. Clone the repository: git clone https://github.com/yourusername/mcp-server-python-template.git cd mcp-server-python-template

2. (Optional) Create a virtual environment and activate it: python -m venv .venv source .venv/bin/activate # On Windows: .venv\Scripts\activate

3. Install the package in editable mode (so changes reflect immediately): pip install -e .

4. Verify installation by listing dependencies (optional): pip list

5. Run the example server (stdio transport by default): python server.py --transport stdio

6. If you want to run SSE transport (for web clients), start with: python server.py --transport sse --host 0.0.0.0 --port 8080

Tips and tips:

• The template includes embedded MCP documentation (protocals/mcp.md and protocals/sdk.md) to help AI tools understand MCP concepts without external references.
• Transports: The provided configuration uses stdio by default. For web-based clients, SSE transport can be enabled as shown in the README example.
• Environment variables are not strictly required for the basic template, but you may want to configure host/port, logging levels, or API keys for external services (e.g., NWS API) as needed.
• If you modify or add tools, decorate them with @mcp.tool() and ensure they are properly registered within the FastMCP instance.
• Ensure Python 3.12+ is available in your environment to satisfy dependencies (mcp, httpx, starlette, uvicorn).
• For troubleshooting, check that your virtual environment is activated and that dependencies are installed in the active environment.