blackwell-systems/mcp-assert

The testing standard for MCP servers. Lint (14 rules), test, and fuzz over real stdio/SSE/HTTP transport. 18 assertion types in YAML. Found 4,794 schema issues across 55 servers. Any language, no mocks, single binary.

23 ★2 forksGoUpdated 18d ago

What you need to know

A testing framework for MCP servers that connects over the real protocol (stdio/SSE/HTTP), runs audit, fuzz, lint and YAML-based assertions, and integrates with pytest, Vitest, Jest, Bun, PHPUnit and Go test, plus CI with a GitHub Action.

Install

pip install mcp-assert
npx @blackwell-systems/mcp-assert
go install github.com/blackwell-systems/mcp-assert/cmd/mcp-assert@latest
brew install blackwell-systems/tap/mcp-assert

Usage

•mcp-assert audit --server 'npx my-mcp-server' for a zero-setup scan
•mcp-assert ci --suite evals/ --threshold 95 for CI with regression detection

Key features

✓Real-protocol testing of any MCP server (any language)
✓Commands: audit, fuzz, init, run, ci, coverage, snapshot, watch, matrix, intercept, lint
✓24 static-analysis lint rules with auto-fix
✓Same YAML assertions across CLI and test frameworks
✓GitHub Action mcp-assert-action

Best for

CI-first, deterministic quality testing of MCP servers

Caveats

⚠A configuration file must be set up for a server before use
⚠Best paired with a config file for real-time access
⚠LLM-as-judge frameworks remain better for subjective outputs

Platforms: macOS · Windows · Linux

Reviewed 2026-08-11

Topics

ai-agentsassertionscideveloper-toolsfuzzinggithub-actions golangjestlintermcpmcp-servermcp-testingmcp-toolsmodel-context-protocolpytestquality-assuranceregression-testingstatic-analysis testingvitest

Stars: 23★
Forks: 2
Language: Go
License: MIT
Created: 2026-04-23
Last push: 2026-08-18