PyMCP Server

PyMCP is a small, asynchronous server that exposes Python functions as remote tools over a WebSocket-compatible protocol. It is designed to be simple to set up, supports hot-reloading of tools, and lets you discover and invoke tools remotely from a client. This makes it easy to build and maintain a modular set of remote actions that can be called from anywhere.

How to use

You run a local PyMCP server and connect to it with a PyMCP client to call tools exposed by your Python modules. Tools can be added, updated, or removed on the fly and the server will hot-reload them without needing a restart. Tools can be organized across multiple files and directories, and can request the server’s internal registry through dependency injection if you need it.

How to install

Prerequisites: ensure Python 3.8+ and Git are installed on your system.

# 1) Install from source
# Replace <repository-url> with the actual repository URL you are using
git clone <repository-url>
cd pymcp

# 2) Install dependencies
pip install -r requirements.txt

# 3) Install the package in editable mode so you can modify code
pip install -e .

Run the server with default settings or customize the network and tool repository path.

pymcp

# Or with custom settings
pymcp --host 0.0.0.0 --port 9000 --tool-repo ./my_tools --log-level DEBUG

Configuration and startup notes

Configure how the server runs by supplying environment variables or command-line options. Common options include the host, port, and where your tools live.

Environment variables to consider (examples shown):

# .env
# Server network settings
PYMCP_HOST=127.0.0.1
PYMCP_PORT=8765

# List of paths to user-defined tool directories, separated by commas
PYMCP_USER_TOOL_REPOS=./my_custom_tools,../shared_tools,/home/user/tools

# Logging level
PYMCP_LOG_LEVEL=INFO

Tool discovery and hot-reloading

PyMCP scans the directories you point to with the tool repository setting. It loads tool definitions from Python files, building a registry of available tools. If you add, modify, or delete a Python file in those directories, the server automatically rebuilds the registry and swaps to the new one without restarting.

The server supports lightweight dependency injection. If a tool function has a parameter named tool_registry, the server automatically passes the ToolRegistry instance at execution time.

Tools exposed by the server

You can expose functions as remote tools using the provided decorator. For example, you can define a simple addition tool and a data retrieval tool that other clients can call.

import pymcp

@pymcp.tool
def add(a: int, b: int) -> int:
    """
    Add two integers
    """
    return a + b

@pymcp.tool
def retrieve_data() -> str:
    """
    Retrieve user data from source
    """
    return data

Available tools

add

Add two integers and return the sum.

retrieve_data

Retrieve user data from the data source.