mcp-worker-sdk

Worker Protocol Python runtime reference implementation — a universal MCP tool runtime SDK.

Write plain Python functions with the @worker.tool decorator and automatically get standard endpoints, schema generation, parameter validation, standardized errors, lifecycle hooks, and built-in database drivers.

mcp-worker-sdk is the Python runtime binding of the language-agnostic Worker Protocol. It is Hub-agnostic: omit hub_url to run it standalone as a standard HTTP tool service that any aggregator (Hub / MCP gateway) can consume.

Install

pip install mcp-worker-sdk

With all built-in database drivers:

pip install "mcp-worker-sdk[db]"

Quick start

from mcp_worker_sdk import Worker
from mcp_worker_sdk.adapters import DBAdapter

worker = Worker(
    name="notes",
    adapter=DBAdapter("sqlite", ":memory:"),
    # hub_url="https://hub.example.com",   # optional; omit to run standalone
)


@worker.tool(
    id="notes_greet",
    title="Greet",
    description="Return a greeting for a name",
)
def greet(name: str = "World"):
    """Return a greeting.

    :param name: who to greet
    """
    return {"message": f"Hello, {name}!"}


if __name__ == "__main__":
    worker.run(port=9100)

Then:

curl http://localhost:9100/health
curl http://localhost:9100/tools
curl -X POST http://localhost:9100/execute \
  -H "Content-Type: application/json" \
  -d '{"tool_id":"notes_greet","params":{"name":"Mavis"}}'

Adapters

DBAdapter built-in drivers

postgresql (psycopg), mysql (pymysql), sqlite (sqlite3), qdrant (qdrant-client), neo4j (neo4j), redis (redis), mongodb (pymongo).

CLI scaffold

mcp-worker create my-worker              # default HTTPAdapter
mcp-worker create my-worker --adapter db

License

Apache-2.0