__ __ ____ ____ ____ _
| \/ |/ ___| _ \ | _ \ ___ ___| |_ ___ _ __
| |\/| | | | |_) | | | | |/ _ \ / __| __/ _ \| '__|
| | | | |___| __/ | |_| | (_) | (__| || (_) | |
|_| |_|\____|_| |____/ \___/ \___|\__\___/|_|
Compliance testing for MCP servers. 50+ checks. One command.
MCP Doctor is a free, open-source CLI that tests any Model Context Protocol server against 50+ compliance checks. It validates protocol correctness, tool/resource/prompt schemas, error handling, and security -- then gives you a score out of 100.
npx mcpdoctor test "node my-server.js" MCP Doctor v1.0.0 — Compliance Test Suite
──────────────────────────────────────────
Server: my-server v1.0.0
Transport: stdio
Protocol: 2024-11-05
PROTOCOL
✓ Initialize Handshake 2ms
✓ Initialized Notification Accepted 0ms
✓ Server Info Present 0ms
✓ Capabilities Format Valid 0ms
✓ Ping Response 15ms
✓ JSON-RPC 2.0 Envelope 1ms
✓ Error Code Compliance 3ms
✓ Unknown Method Returns Error 5ms
✓ Request ID Echoed 1ms
✓ Protocol Version Accepted 0ms
TOOLS
✓ tools/list Returns Valid Array 8ms
✓ Tool Schema Has Required Fields 3ms
✓ Input Schema Is Valid JSON Schema 2ms
✓ Tool Call Returns Content Array 12ms
✓ Text Content Has Type + Text 1ms
✗ Tool Call With Invalid Params Returns Error 4ms
→ Server returned 200 instead of error response
✓ Empty Arguments Handled 5ms
✓ Tool Names Are Unique 0ms
✓ Tool Description Present 0ms
✓ Large Payload Handled 45ms
RESOURCES
✓ resources/list Returns Valid Array 6ms
✓ Resource URI Format Valid 1ms
✓ Resource Read Returns Contents 9ms
✓ MIME Type Present 0ms
✓ Template URI Expansion 3ms
○ Subscribe Notification (skipped — not declared)
✓ Resource Names Unique 0ms
✓ Invalid URI Returns Error 2ms
PROMPTS
✓ prompts/list Returns Valid Array 5ms
✓ Prompt Has Name + Description 0ms
✓ Prompt Arguments Defined 1ms
✓ Get Prompt Returns Messages 7ms
✓ Messages Have Role + Content 0ms
✗ Required Argument Missing Returns Error 3ms
→ Server returned messages instead of error
✓ Prompt Names Unique 0ms
ERROR HANDLING
✓ Malformed JSON-RPC Rejected 2ms
✓ Missing Method Returns Error 1ms
✓ Concurrent Requests Handled 28ms
✓ Timeout Behavior 5001ms
✓ Invalid Params Rejected 3ms
✓ Oversized Payload Rejected 11ms
✓ Null ID Request Handled 1ms
✓ Batch Not Supported Error 2ms
SECURITY
✓ No Environment Variable Leaks 4ms
✓ Path Traversal Rejected 6ms
✓ SQL Injection in Tool Args 3ms
✓ Command Injection Blocked 5ms
✓ Sensitive Field Redaction 2ms
○ TLS Certificate Valid (skipped — stdio transport)
✓ No Verbose Error Stack Traces 1ms
──────────────────────────────────────────
Score: 92/100 (A)
48 passed · 2 failed · 3 skipped · 0 errors
Total time: 1.2s
The MCP ecosystem is growing fast. Servers vary wildly in quality -- some return malformed JSON-RPC, skip required schema fields, or leak environment variables in error messages. Before MCP Doctor, there was no standard way to verify compliance.
| Manual Testing | No Testing | MCP Doctor | |
|---|---|---|---|
| Protocol coverage | Partial, ad hoc | None | 50+ automated checks |
| Time per run | 30-60 min | 0 | ~2 seconds |
| Consistency | Varies by tester | N/A | Deterministic |
| CI/CD ready | No | No | Yes (JSON + exit codes) |
| Security checks | Usually skipped | None | Path traversal, injection, leaks |
| Score / grade | No | No | 0-100 score with A-F grade |
# Test a local stdio server
npx mcpdoctor test "node my-server.js"
# Test an npm package
npx mcpdoctor test "npx @company/mcp-server"
# Test an HTTP/SSE server
npx mcpdoctor test --transport sse --url http://localhost:3001/sse
# Test with env vars
npx mcpdoctor test "node server.js" --env API_KEY=abc123
# JSON output for CI
npx mcpdoctor test "node server.js" --format json- 50+ compliance checks across 6 categories -- protocol, tools, resources, prompts, errors, security
- Zero config -- point it at any MCP server and go
- Three transports -- stdio, SSE, and streamable-http
- Scoring system -- 0-100 score with letter grades (A through F)
- Multiple output formats -- pretty terminal, JSON, Markdown
- Category filtering -- run only the checks you care about
- CI/CD ready -- exit code 1 on failure, JSON output for automation
- Security testing -- checks for env leaks, path traversal, SQL injection, command injection
- Fast -- full suite runs in ~2 seconds
- No account required -- fully local, no API keys, no telemetry
mcpdoctor test <command> [options]
Arguments:
command Server command to test (e.g., "node server.js")
Options:
--transport <type> Transport type: stdio (default), sse, streamable-http
--url <url> Server URL (for sse/http transports)
--env <key=value> Environment variables (repeatable)
--timeout <ms> Per-check timeout in ms (default: 10000)
--format <type> Output format: pretty (default), json, markdown
--category <cat> Run only checks in this category
--verbose Show detailed output for each check
--version Show version
--help Show help
| Code | Meaning |
|---|---|
0 |
All checks passed |
1 |
One or more checks failed or errored |
| Category | Checks | What it tests |
|---|---|---|
| protocol | 10 | Initialize handshake, JSON-RPC 2.0 compliance, error codes, ping |
| tools | 10 | Tool listing, schemas, calls, content format, uniqueness |
| resources | 8 | Resource listing, URIs, reading, templates, subscriptions |
| prompts | 7 | Prompt listing, arguments, message format, required params |
| error_handling | 8 | Timeouts, malformed input, concurrency, oversized payloads |
| security | 7 | Env leak detection, path traversal, injection, stack traces |
name: MCP Compliance
on: [push, pull_request]
jobs:
mcp-test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '20'
- run: npm install
- name: Run MCP compliance tests
run: npx mcpdoctor test "node dist/server.js" --format json > mcp-report.json
- name: Check score
run: |
SCORE=$(jq '.score' mcp-report.json)
echo "MCP Compliance Score: $SCORE/100"
if [ "$SCORE" -lt 80 ]; then
echo "::error::MCP compliance score $SCORE is below threshold (80)"
exit 1
fi
- name: Upload report
if: always()
uses: actions/upload-artifact@v4
with:
name: mcp-compliance-report
path: mcp-report.json - name: Generate markdown report
if: github.event_name == 'pull_request'
run: npx mcpdoctor test "node dist/server.js" --format markdown > mcp-report.md
- name: Comment on PR
if: github.event_name == 'pull_request'
uses: marocchino/sticky-pull-request-comment@v2
with:
path: mcp-report.mdmcpdoctor/
cli/ # The npx mcpdoctor CLI (published to npm)
api/ # Optional hosted API for persistent monitoring
site/ # mcpdoctor.ai website
The CLI is the primary tool. The API and site are optional components for teams that want persistent dashboards and scheduled monitoring.
Contributions are welcome. To get started:
git clone https://github.com/parallelromb/mcpdoctor.git
cd mcpdoctor/cli
npm install
npm run devTo add a new check, edit cli/src/spec.ts. Each check is a function that receives an MCP client and returns pass/fail/skip with an optional message.
- Website: mcpdoctor.ai
- npm: npmjs.com/package/mcpdoctor
- GitHub: github.com/parallelromb/mcpdoctor
MIT -- see LICENSE for details.
Built by Sri • Free and open source forever