🇷🇺 Русская версия

MCP Server Tester - High-performance testing framework for MCP servers with SSE-HTTP-STDIO protocol support, Bearer token authorization, and declarative test scenarios

A high-performance tool for testing MCP servers with SSE-HTTP-STDIO protocol support, Bearer token authorization, and test scenario writing through configuration files without programming.

🚀 Available on All Platforms

npm version PyPI version Docker Hub GitHub Actions

👨‍💻 Author

Created by @ii_pomogator - AI Assistant Channel on Telegram

---

✨ Key Features

• 🔌 Full SSE-HTTP-STDIO protocol support for MCP servers
• 🔐 Bearer token authorization for secure testing
• 📝 Declarative tests - write scenarios in YAML without programming
• 🎯 Multiple assertion types - verify any aspects of responses
• 📊 Detailed reports on test execution
• 🐳 Docker support for isolated testing
• 🔄 CI/CD integration via GitHub Actions

📦 Installation

NPM (Node.js)

npm install -g mcp-server-tester-sse-http-stdio

PyPI (Python)

pip install mcp-server-tester

Docker

docker pull stgmt/mcp-server-tester

🚀 Quick Start

Using NPM

npx mcp-server-tester-sse-http-stdio test --test test.yaml --server-config config.json

Using Python

mcp-server-tester test --test test.yaml --server-config config.json

Using Docker

docker run -v $(pwd):/workspace stgmt/mcp-server-tester test --test /workspace/test.yaml

📝 Example Test Scenario

name: "MCP Server Basic Test"
description: "Testing basic MCP server functionality"
timeout: 30000

tests:
  - name: "Initialize connection"
    type: "initialize"
    params:
      protocolVersion: "1.0.0"
      capabilities:
        tools: true
    expect:
      status: "success"
      capabilities:
        tools: true

  - name: "List available tools"
    type: "tools/list"
    expect:
      status: "success"
      tools:
        - name: "echo"
          description: "Echo tool"

  - name: "Call echo tool"
    type: "tools/call"
    params:
      name: "echo"
      arguments:
        message: "Hello, MCP!"
    expect:
      status: "success"
      result:
        message: "Hello, MCP!"

📋 Server Configuration

{
  "mcpServers": {
    "test-server": {
      "command": "node",
      "args": ["server.js"],
      "env": {
        "BEARER_TOKEN": "your-secret-token"
      },
      "transport": {
        "type": "sse",
        "config": {
          "url": "http://localhost:3000/sse",
          "headers": {
            "Authorization": "Bearer your-secret-token"
          }
        }
      }
    }
  }
}

🛠️ CLI Commands

Run Tests

mcp-server-tester test --test <test-file> --server-config <config-file> [options]

Options:
  --server-name <name>  Server name from configuration
  --verbose            Verbose output
  --json-output        Output results in JSON format
  --timeout <ms>       Test timeout (default: 30000)

Validate Configuration

mcp-server-tester validate --test <test-file>

List Available Server Tools

mcp-server-tester tools --server-config <config-file> --server-name <name>

🐳 Docker Support

Simple Run

docker run -v $(pwd):/workspace stgmt/mcp-server-tester \
  test --test /workspace/test.yaml --server-config /workspace/config.json

Docker Compose

version: '3.8'
services:
  mcp-tester:
    image: stgmt/mcp-server-tester
    volumes:
      - ./tests:/workspace/tests
      - ./config:/workspace/config
    command: test --test /workspace/tests/test.yaml --server-config /workspace/config/server.json

Supported Platforms

Platform	Architecture	Status
Linux	amd64	✅
Linux	arm64	✅
macOS	amd64	✅
macOS	arm64	✅
Windows	amd64	✅

🔄 CI/CD Integration

GitHub Actions

name: MCP Server Tests
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Run MCP Server Tests
        run: |
          docker run -v ${{ github.workspace }}:/workspace \
            stgmt/mcp-server-tester test \
            --test /workspace/tests/test.yaml \
            --server-config /workspace/config.json

GitLab CI

mcp-tests:
  image: stgmt/mcp-server-tester
  script:
    - mcp-server-tester test --test tests/test.yaml --server-config config.json

📊 Assertion Examples

Response Structure Validation

expect:
  status: "success"
  result:
    type: "object"
    properties:
      message:
        type: "string"
        pattern: "^Hello.*"
      count:
        type: "number"
        minimum: 0

Array Validation

expect:
  tools:
    type: "array"
    minItems: 1
    items:
      type: "object"
      required: ["name", "description"]

Conditional Validation

expect:
  oneOf:
    - status: "success"
      result: { processed: true }
    - status: "pending"
      result: { queued: true }

🔧 Advanced Features

Environment Variables

tests:
  - name: "Test with env variables"
    env:
      API_KEY: "${TEST_API_KEY}"
      BASE_URL: "${TEST_BASE_URL:-http://localhost:3000}"

Sequential Tests with Dependencies

tests:
  - name: "Create resource"
    id: "create"
    type: "tools/call"
    params:
      name: "create_resource"
    capture:
      resource_id: "$.result.id"
  
  - name: "Get created resource"
    depends_on: ["create"]
    type: "tools/call"
    params:
      name: "get_resource"
      arguments:
        id: "${resource_id}"

Parallel Execution

parallel_groups:
  - name: "Performance tests"
    tests:
      - name: "Test 1"
      - name: "Test 2"
      - name: "Test 3"

📚 Documentation

• Complete Guide
• API Reference
• Test Examples
• FAQ

🤝 Contributing

We welcome contributions to the project! See CONTRIBUTING.md for details.

📄 License

MIT License - see LICENSE file.

🔗 Links

• GitHub: stgmt/mcp-server-tester-sse-http-stdio
• NPM: mcp-server-tester-sse-http-stdio
• PyPI: mcp-server-tester
• Docker Hub: stgmt/mcp-server-tester

💬 Support

• Create Issue
• Discussions
• Email: [email protected]

---

Developed with ❤️ by @ii_pomogator