py-mcp-server-template

You will run a Python MCP (Model Context Protocol) server that can communicate with MCP clients. This server template uses uv for packaging and virtual environment management, making it easy to create, run, and test your own MCP services. You can start from this template and customize it to your needs while keeping a clean separation between your server logic and client integrations.

How to use

You will start the MCP server locally and connect clients to it. The server runs in stdio mode, which is the usual setup expected by MCP clients. You configure the client to launch your server through the helper command, and the client will communicate over standard input/output with the running process.

How to install

Prerequisites you need on your machine before starting are: Python installed on your system and the uv packaging tool available in your environment. You will also need to have your project cloned from your own repository and prepared with the necessary files.

# 1) Clone your forked repository
git clone https://github.com/YOUR_USERNAME/YOUR_REPOSITORY_NAME.git
cd YOUR_REPOSITORY_NAME

# 2) Create and activate the virtual environment using uv
uv venv
source .venv/bin/activate  # On macOS/Linux
# .venv\Scripts\activate   # On Windows

# 3) Install dependencies
uv pip install .

Additional configuration and notes

To run the server locally, start it with the following command. This starts the MCP server which listens for connections via stdio.

uv run python mcp_server.py

Integrating with MCP clients like Claude Desktop or Cursor

Configure your MCP client to launch your server process. Use the full path to your Python interpreter inside the virtual environment and the path to your server script. The configuration typically includes the command to run the server, the arguments, and the working directory.

{
  "mcpServers": {
    "my-custom-python-server": {
      "command": "uv",
      "args": [
        "run",
        "--python",
        "/ABSOLUTE/PATH/TO/PARENT/FOLDER/YOUR_REPOSITORY_NAME/.venv/bin/python",
        "/ABSOLUTE/PATH/TO/PARENT/FOLDER/YOUR_REPOSITORY_NAME/mcp_server.py"
      ],
      "workingDirectory": "/ABSOLUTE/PATH/TO/PARENT/FOLDER/YOUR_REPOSITORY_NAME"
    }
  }
}

Notes on transport and defaults

The server listens on stdio by default, which is what MCP clients like Cursor typically expect. Ensure your client points to the correct working directory and uses the full path to the Python interpreter in your virtual environment to avoid path resolution issues.

Available tools

uv

Python packaging and virtual environment management tool used to create, manage, and run the MCP server environment.

mcp_server

The MCP server script that runs and serves requests using stdio transport.