mcp-testclient

pytest-native TestClient for the MCP Python SDK Server class.

Using FastMCP? You already have Client(server) built in. mcp-testclient targets the official mcp.server.lowlevel.Server class only.

Why

The MCP Python SDK ships a Server class with no built-in test transport. Testing requires spawning a subprocess or standing up a real HTTP server — until now.

mcp-testclient wires your Server directly to a ClientSession using anyio memory streams. No subprocess. No network. No stdio. In-process, in a single pytest function.

from mcp.server.lowlevel import Server
import mcp.types as types
from mcp_testclient import TestClient

server = Server("my-server")

@server.list_tools()
async def list_tools():
    return [types.Tool(name="add", description="Add two numbers",
                       inputSchema={"type": "object", "properties":
                           {"a": {"type": "number"}, "b": {"type": "number"}}})]

@server.call_tool()
async def call_tool(name, arguments):
    return [types.TextContent(type="text", text=str(arguments["a"] + arguments["b"]))]

def test_add():
    with TestClient(server) as client:
        tools = client.list_tools()
        assert tools[0].name == "add"

        result = client.call_tool("add", {"a": 1, "b": 2})
        assert result[0].text == "3"

Install

pip install mcp-testclient

API

with TestClient(server) as client:
    client.list_tools()                            # → list[types.Tool]
    client.call_tool("name", {"arg": "value"})    # → list[TextContent | ...]
    client.list_resources()                        # → list[types.Resource]
    client.read_resource("resource://uri")         # → list[TextResourceContents | ...]
    client.list_prompts()                          # → list[types.Prompt]
    client.get_prompt("name", {"arg": "value"})   # → GetPromptResult

call_tool raises RuntimeError if the server returns isError=True.

Compatibility

• Python 3.10, 3.11, 3.12
• mcp >= 1.0.0 (tested on 1.26.0)

Known Issues

MCP SDK v1.9.1+: default host changed to 127.0.0.1

Docker containers will be unreachable externally. Explicitly set host='0.0.0.0' in your FastMCP or server config if deploying in a container.

MCP SDK v1.9.4+: Streamable HTTP incompatible with Cloud Run

If you're hitting connection errors on Cloud Run after upgrading, downgrade the SDK or use SSE transport temporarily until a fix ships upstream.

SSE transport deprecated as of April 1, 2026 (grace period through June 30, 2026)

All SSE-based MCP servers need to migrate to Streamable HTTP by end of June. See the MCP spec migration guide for details.

MCP Registry

mcp-name: io.github.peytongreen-dev/mcp-testclient