Skip to main content
Glama

PyMCP

by sokinpui

PyMCP

PyMCP is a simple, tiny, and asynchronous server and client implementation for the Modern Context Protocol (MCP).

Features

  • Simple Tool Definition: Easily expose functions as remote tools using a simple @tool decorator.
  • Hot-Reloading: Tools can be added, removed, or modified on the fly, and the server will hot-reload them without a restart.

Quick Start

Running the Server

  1. Installation (from source):
    git clone <repository-url> cd pymcp pip install -r requirements.txt pip install -e .
  2. Run the Server:
    • run with default settings:
    pymcp
    • run with custom settings:
    pymcp --host 0.0.0.0 --port 9000 --tool-repo ./my_tools --log-level DEBUG

Using the Client

import asyncio import pymcp async def main(): try: async with pymcp.Client("localhost", 8765) as client: # Ping the server pong = await client.call("ping") # Call the custom 'add' tool result = await client.call("add", a=5, b=7) print(f"5 + 7 = {result}") # Discover available tools tools = await client.call("list_tools_available") print("Available tools:", tools) except Exception as e: print(f"An error occurred: {e}") if __name__ == "__main__": asyncio.run(main())

Configuration

  • Arguments passed to start_server().
  • Command-line arguments (e.g., --port).
  • Environment variables (e.g., PYMCP_PORT=9000).
  • Values in a .env file in your project's root.
  • Default values in the Settings class.

all configuration options:

# .env # Server network settings # PYMCP_HOST=<your_host_address> PYMCP_HOST=127.0.0.1 # PYMCP_PORT=<your_port_number> PYMCP_PORT=8765 # List of paths to user-defined tool directories. # Paths should be separated by commas. # absolute or relative paths # Example: /path/to/my_tools,/another/path/for_tools PYMCP_USER_TOOL_REPOS=./my_custom_tools,../shared_tools,/home/user/tools # Logging level # Valid values: DEBUG, INFO, WARNING, ERROR, CRITICAL PYMCP_LOG_LEVEL=INFO

Server

request->response flow
client -> connection manager -> validator -> router -> tool executor -> return result -> client
create a tool
import pymcp @pymcp.tool def add(a: int, b: int) -> int: """ Add two integer numbers. argument a: First integer number. argument b: Second integer number. return: The sum of the two numbers. """ return a + b @pymcp.tool def retrieve_data() -> str: """ Retrieve user data from source no arguments is needed """ return data

Tool Repository discovery

The server discovers tools by scanning all .py files within the directories specified by the --tool-repo CLI argument or the PYMCP_TOOL_REPOS environment variable.

You can organize your tools into multiple files and directories. The loader will scan them recursively.

example directory structure:

my_tools/ ├── __init__.py ├── math_tools.py ├── string_tools.py └── data_tools/ ├── __init__.py ├── user_data.py └── system_data.py second_tools/ ├── __init__.py ├── network_tools.py └── file_tools.py
Hot-Reloading

The server watches the tool repositories for file changes. If you add, modify, or delete a Python file in a tool directory, the server will automatically perform a reload:

  1. It rebuilds the entire tool registry from scratch.
  2. It atomically swaps the old registry with the new one.

This allows you to update tool logic on a live server without a restart.

PyMCP supports a simple form of dependency injection. If a tool function's signature includes a parameter named tool_registry, the server will automatically provide the ToolRegistry instance to it at execution time.


Client

Connect to the server
import pymcp async def main(): async with pymcp.Client("localhost", 8765) as client: result = await client.call("ping") print(result)
request execute tools
import pymcp async def main(): async with pymcp.Client("localhost", 8765) as client: result = await client.call("add", a=5, b=7) print(f"5 + 7 = {result}") tools = await client.call("list_tools_available") print("Available tools:", tools)

Protocol

PyMCP uses a simple, JSON-based messaging protocol over a standard WebSocket connection.

  • Client-to-Server: Requests
{ "header": { "correlation_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef" }, "body": { "tool": "add", "args": { "a": 5, "b": 10 } } }
  • Server-to-Client: Responses (Success)
{ "status": "success", "header": { "correlation_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef" }, "body": { "tool": "add", "result": 15 }, "error": null }
  • Server-to-Client: Responses (Error)
{ "status": "error", "header": { "correlation_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef" }, "body": null, "error": { "code": "execution_error", "message": "An unexpected error occurred while executing tool 'add'." } }

Design

PyMCP is designed to be simple, extensible, and easy to use. The server itself is just a WebSocket server that handles incoming requests, validates them, routes them to the appropriate tool executor, and returns the results.

No concept like "resources", "tools", or "prompts", since all of them are just a function that input something and return something. Everything is a tool. It leaves to user defining the scope of the tools.

The internal tools like list_tools_available and ping, are also some type of "tools". Tools and Server are decoupled. core tools are like extension of the server.

-
security - not tested
F
license - not found
-
quality - not tested

A simple, tiny, and asynchronous server and client implementation for the Modern Context Protocol that allows you to easily expose functions as remote tools using a decorator with hot-reloading capability.

  1. Features
    1. Quick Start
      1. Running the Server
      2. Using the Client
      3. Configuration
      4. Server
      5. Tool Repository discovery
      6. Client
      7. Protocol
    2. Design

      Related MCP Servers

      • -
        security
        A
        license
        -
        quality
        A simple implementation of a Model Context Protocol server that demonstrates core functionality including mathematical tools (add, subtract) and personalized greeting resources.
        Last updated -
        56
        Python
        GPL 3.0
      • -
        security
        F
        license
        -
        quality
        A sample implementation of Model Context Protocol server demonstrating core functionality with simple arithmetic tools and greeting resources.
        Last updated -
        Python
      • A
        security
        A
        license
        A
        quality
        A comprehensive Model Context Protocol server providing access to 70+ IT tools for developers and system administrators, including encoding/decoding, text manipulation, hashing, and network utilities.
        Last updated -
        76
        400
        6
        TypeScript
        MIT License
        • Linux
      • A
        security
        F
        license
        A
        quality
        A Model Context Protocol server implementation that provides basic utility tools including echo, uppercase text conversion, and mathematical calculations.
        Last updated -
        3
        738
        JavaScript

      View all related MCP servers

      MCP directory API

      We provide all the information about MCP servers via our MCP API.

      curl -X GET 'https://glama.ai/api/mcp/v1/servers/sokinpui/pymcp'

      If you have feedback or need assistance with the MCP directory API, please join our Discord server