mcpserver.so LogoMCPFly
Submit
Python MCP Server Starter logo

Python MCP Server Starter

by ltwlf

Development/ExamplesPythonServerTemplate

A template repository for creating Python applications using the Model Context Protocol (MCP) and the MCP Python SDK. It provides a starting point for building MCP servers with tools and resources.

View on GitHub

Last updated: N/A

Python MCP Server Starter Template

A template repository for creating Python applications using the Model Context Protocol (MCP) and the MCP Python SDK.

Features

  • Implements an MCP server using the mcp Python SDK (FastMCP).
  • Exposes MCP Tools (functions callable by LLMs) and Resources (data accessible by LLMs).
  • Clean, modular architecture
  • Easy tool and resource registration
  • Command-line interface with customizable options
  • Ready for production deployment
  • Built-in debug capabilities using debugpy with VS Code integration
  • Development tools configured (using uv for environment/package management)
  • Docker support for containerized deployment

Getting Started

Prerequisites

  • Python 3.10 or higher
  • uv (Recommended for environment and package management)
  • MCP Inspector (Recommended visual tool for testing/debugging MCP servers)
  • [Optional] Git
  • [Optional] Docker for containerized deployment

Installation

  1. Clone or Use as Template: Get the code.

    git clone https://github.com/ltwlf/python-mcp-starter.git your-repo-name # Or use GitHub's "Use this template" button
cd your-repo-name

  2. Rename the Project: Rename the core components:

    • Rename the hello_mcp_server directory to your desired Python package name (e.g., my_awesome_mcp).
    • Search and replace hello-mcp-server (in pyproject.toml, README.md, Dockerfile, docker-compose.yml) with your project name (e.g., my-awesome-mcp).
    • Search and replace hello_mcp_server (in Python import statements like in main.py, tests/test_server.py, pyproject.toml scripts section) with your new package name.
    • Update the APP_ID in your renamed server.py file.
    • Update .vscode/launch.json configuration file to reflect your new project and package names.

  3. Create Virtual Environment:

    # Create the virtual environment
uv venv

# Activate the environment (Windows PowerShell)
.venv\Scripts\Activate.ps1

# Or for other shells:

# source .venv/bin/activate  (Linux/macOS)

# .venv\Scripts\activate.bat (Windows Command Prompt)

  4. Install Dependencies:

    uv pip install -e ".[dev]"

Running the MCP Server for Development

You can run the server directly using uv run or the mcp CLI tool provided by the SDK. This allows testing with tools like the MCP Inspector.

In stdio mode (for MCP Inspector)

Method 1: Using uv run

# Ensure your virtual environment is active first
# Replace 'hello-mcp-server' with the script name defined in your pyproject.toml
uv run your-script-name

Method 2: Using the mcp CLI tool

# Ensure your virtual environment is active first
# Replace 'hello_mcp_server' with your renamed package directory
mcp dev ./your_package_name/server.py
In SSE mode
# Ensure your virtual environment is active first
# Replace 'hello-mcp-server' with your script name
uv run your-script-name --sse

Or with custom host and port:

# Ensure your virtual environment is active first
# Replace 'hello-mcp-server' with your script name
uv run your-script-name --sse --host 127.0.0.1 --port 9000

Docker Deployment

Update the Dockerfile and docker-compose.yml to reflect your renamed project/package before building.

# Build and run with Docker Compose
docker-compose up -d

# Or build and run directly with Docker
# Replace 'hello-mcp-server' with your image name
docker build -t your-image-name .
docker run -p 8000:8000 your-image-name

Development

Debugging

This project includes built-in debugging capabilities using debugpy. There are two main ways to debug your MCP server:

Using the Debug Module

The project includes a dedicated debug module that makes debugging easy:

# Using uv (recommended)
uv run mcp-debug

Connect to the MCP Inspector first, and once connected, use the VS Code debug configuration Attach to MCP worker to attach the debugger for debugging

Using VS Code

VS Code debugging is configured with several launch configurations:

  1. Attach to MCP worker - Attach to a running MCP server (attach this to a running mcp-debug)
  2. Launch MCP Server (SSE) - Launch the MCP server directly with server-sent events

For the best experience:

  1. First, run uv run mcp-debug in a terminal
  2. Then, to set breakpoints, use the VS Code debugger with the "Attach to MCP worker" configuration

Note: Make sure you have your virtual environment set up with uv venv and uv pip install -e .[dev] before debugging.

  1. Check Python interpreter:
    • Ensure VS Code is using the correct Python interpreter from your virtual environment
    • If needed, select the interpreter using the Python extension's "Select Interpreter" command

To use these configurations:

  1. Open the Run and Debug panel in VS Code (Ctrl+Shift+D)
  2. Select the desired configuration from the dropdown
  3. Click the play button or press F5
Security Considerations
  • Debug mode should never be used in production environments
  • The debugger exposes a network port that could be exploited if not secured
  • Always use debugging on trusted networks or with proper security measures in place

Adding New Tools

Add new tools using the @mcp.tool() decorator in your_package_name/server.py:

# your_package_name/server.py
from mcp.server.fastmcp import FastMCP, Context

mcp = FastMCP("your-app-id") # Ensure APP_ID matches your project

# ... existing tools ...

# Add your new tool
@mcp.tool()
async def my_new_tool(param1: str, param2: int, ctx: Context) -> dict:
    """
    Description of what your tool does.
    Use the ctx object to report progress, log info, or read resources.
    """
    ctx.info(f"Running my_new_tool with {param1=}, {param2=}")
    # Tool implementation
    result = f"Processed {param1} {param2} times"
    await ctx.report_progress(1, 1) # Example progress
    return {"result": result}

Adding New Resources

Add new resources using the @mcp.resource() decorator in your_package_name/server.py:

# your_package_name/server.py
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("your-app-id") # Ensure APP_ID matches your project

# ... existing resources ...

# Add resources
@mcp.resource("your-resource-uri")
def your_resource_func():
    """Returns application settings."""
    return {"theme": "dark", "language": "en"}

Testing

Make sure the import statements in tests/test_server.py point to your renamed package.

pytest

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments