Mcpdoctor

   __  __  ____ ____    ____             _
  |  \/  |/ ___|  _ \  |  _ \  ___   ___| |_ ___  _ __
  | |\/| | |   | |_) | | | | |/ _ \ / __| __/ _ \| '__|
  | |  | | |___|  __/  | |_| | (_) | (__| || (_) | |
  |_|  |_|\____|_|     |____/ \___/ \___|\__\___/|_|

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"

Terminal Output

  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

Why MCP Doctor?

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.

Quick Start

# 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

Features

• 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

CLI Reference

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

Exit Codes

Check Categories

CI/CD Integration

GitHub Actions

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

PR Comment with Markdown Report

      - 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.md

Project Structure

mcpdoctor/
  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.

Contributing

Contributions are welcome. To get started:

git clone https://github.com/parallelromb/mcpdoctor.git
cd mcpdoctor/cli
npm install
npm run dev

To 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.

Links

• Website: mcpdoctor.ai
• npm: npmjs.com/package/mcpdoctor
• GitHub: github.com/parallelromb/mcpdoctor

License

MIT -- see LICENSE for details.