pytest-mcptest

Test your MCP servers like you test everything else.

A pytest plugin for Model Context Protocol servers. It starts your server, connects a client, and gives you fixtures and assertions for tools, resources, and prompts. It works in-process, over stdio, or over Streamable HTTP. It also tests servers written in other languages, such as Node.js or Go, as long as they speak MCP over stdio or HTTP.

pip install pytest-mcptest

The import name is pytest_mcp. Requires Python 3.10+ and the official mcp SDK 2.x.

Quick start

# test_server.py
import pytest
from pytest_mcp import assert_tool_call, assert_tool_error

from my_server import mcp  # your MCPServer instance

pytestmark = pytest.mark.mcp_server(mcp)


async def test_add(mcp_client):
    await assert_tool_call(mcp_client, "add", {"a": 2, "b": 3}, expected=5)


async def test_divide_by_zero_fails_cleanly(mcp_client):
    await assert_tool_error(mcp_client, "divide", {"a": 1, "b": 0}, match="zero")

pytest

You don't need @pytest.mark.anyio or pytest-asyncio. Any async test that uses mcp_client runs automatically.

Test any server with zero code

pytest --pyargs pytest_mcp.suite --mcp-server "python server.py"
pytest --pyargs pytest_mcp.suite --mcp-server "npx -y @modelcontextprotocol/server-filesystem /tmp"
pytest --pyargs pytest_mcp.suite --mcp-server http://localhost:8000/mcp

The built-in suite checks these things:

• The handshake completes.
• Tool names follow SEP-986 and are unique.
• Every tool is described.
• inputSchema and outputSchema are valid JSON Schema.
• Every listed resource is readable.
• Prompt names are unique.

Has your server migrated to the 2026-07-28 spec?

pytest --pyargs pytest_mcp.suite --mcp-server "python server.py" --mcp-spec-version 2026-07-28

The suite fails if the server negotiates an older protocol version. For example, the official filesystem server still speaks 2025-11-25.

Pointing at your server

Pick one. They are listed from most specific to least specific.

A target can be any of these:

Per-test setup, such as a fresh temp directory for each test:

@pytest.fixture
def mcp_server(tmp_path):
    return stdio("npx", "-y", "@modelcontextprotocol/server-filesystem", str(tmp_path))

Assertions

Each assertion is async, takes mcp_client first, and returns what it fetched, so you can keep asserting on the result.

Failure messages show what the server actually returned:

AssertionError: tool 'add' returned an unexpected value
  expected: 6
  is_error: False
  text: '5'
  structured_content: {'result': 5}

mcp_client also exposes every mcp.Client method (call_tool, read_resource, get_prompt, and so on), plus call(name, **kwargs), tool_names(), and list_all_tools(), list_all_resources(), and list_all_prompts(), which follow pagination. Use result_text(result) to get the text of any result.

Fixtures and options

Outside pytest, async with pytest_mcp.connect(target) as client: gives you the same client.

GitHub Actions

name: test
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with: { python-version: "3.13" }
      - run: pip install -e . pytest-mcptest
      - run: pytest
      - run: pytest --pyargs pytest_mcp.suite --mcp-server "python server.py"

Tips

• With MCPServer, raise ToolError (from mcp.server.mcpserver.exceptions) for expected failures. The client only sees messages from ToolError. Any other exception is masked as "Error executing tool <name>", and assert_tool_error(..., match=...) makes that easy to catch.
• Use in-process targets for speed and stdio targets for realism. Run both if you can.

Roadmap

• v0.1 (this release): fixtures, assertions, stdio, HTTP, and in-process transports, plus the conformance suite.
• v0.2: mcp-mock, which adds record/replay and mock MCP servers for testing agents.
• Later: session-scoped clients, tool-description poisoning checks, and Windows CI.

Contributing

python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest && ruff check . && ruff format --check .

Releasing

1. Bump version in pyproject.toml (and __version__ in pytest_mcp/__init__.py), then merge to main.
2. Run git tag v0.1.1 && git push origin v0.1.1.

The Release workflow checks the tag matches the version, runs the tests, builds, and publishes to PyPI with trusted publishing.

MIT licensed.