[π·πΊ Π ΡΡΡΠΊΠ°Ρ Π²Π΅ΡΡΠΈΡ](./README.ru.md)
# 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
[](https://www.npmjs.com/package/mcp-server-tester-sse-http-stdio)
[](https://pypi.org/project/mcp-server-tester/)
[](https://hub.docker.com/r/stgmt/mcp-server-tester)
[](https://github.com/stgmt/mcp-server-tester-sse-http-stdio/actions)
## π¨βπ» Author
Created by [**@ii_pomogator**](https://t.me/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)
```bash
npm install -g mcp-server-tester-sse-http-stdio
```
### PyPI (Python)
```bash
pip install mcp-server-tester
```
### Docker
```bash
docker pull stgmt/mcp-server-tester
```
## π Quick Start
### Using NPM
```bash
npx mcp-server-tester-sse-http-stdio test --test test.yaml --server-config config.json
```
### Using Python
```bash
mcp-server-tester test --test test.yaml --server-config config.json
```
### Using Docker
```bash
docker run -v $(pwd):/workspace stgmt/mcp-server-tester test --test /workspace/test.yaml
```
## π Example Test Scenario
```yaml
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
```json
{
"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
```bash
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
```bash
mcp-server-tester validate --test <test-file>
```
### List Available Server Tools
```bash
mcp-server-tester tools --server-config <config-file> --server-name <name>
```
## π³ Docker Support
### Simple Run
```bash
docker run -v $(pwd):/workspace stgmt/mcp-server-tester \
test --test /workspace/test.yaml --server-config /workspace/config.json
```
### Docker Compose
```yaml
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
```yaml
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
```yaml
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
```yaml
expect:
status: "success"
result:
type: "object"
properties:
message:
type: "string"
pattern: "^Hello.*"
count:
type: "number"
minimum: 0
```
### Array Validation
```yaml
expect:
tools:
type: "array"
minItems: 1
items:
type: "object"
required: ["name", "description"]
```
### Conditional Validation
```yaml
expect:
oneOf:
- status: "success"
result: { processed: true }
- status: "pending"
result: { queued: true }
```
## π§ Advanced Features
### Environment Variables
```yaml
tests:
- name: "Test with env variables"
env:
API_KEY: "${TEST_API_KEY}"
BASE_URL: "${TEST_BASE_URL:-http://localhost:3000}"
```
### Sequential Tests with Dependencies
```yaml
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
```yaml
parallel_groups:
- name: "Performance tests"
tests:
- name: "Test 1"
- name: "Test 2"
- name: "Test 3"
```
## π Documentation
- [Complete Guide](https://github.com/stgmt/mcp-server-tester-sse-http-stdio/wiki)
- [API Reference](https://github.com/stgmt/mcp-server-tester-sse-http-stdio/wiki/API)
- [Test Examples](https://github.com/stgmt/mcp-server-tester-sse-http-stdio/tree/main/examples)
- [FAQ](https://github.com/stgmt/mcp-server-tester-sse-http-stdio/wiki/FAQ)
## π€ Contributing
We welcome contributions to the project! See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
## π License
MIT License - see [LICENSE](LICENSE) file.
## π Links
- **GitHub**: [stgmt/mcp-server-tester-sse-http-stdio](https://github.com/stgmt/mcp-server-tester-sse-http-stdio)
- **NPM**: [mcp-server-tester-sse-http-stdio](https://www.npmjs.com/package/mcp-server-tester-sse-http-stdio)
- **PyPI**: [mcp-server-tester](https://pypi.org/project/mcp-server-tester/)
- **Docker Hub**: [stgmt/mcp-server-tester](https://hub.docker.com/r/stgmt/mcp-server-tester)
## π¬ Support
- [Create Issue](https://github.com/stgmt/mcp-server-tester-sse-http-stdio/issues)
- [Discussions](https://github.com/stgmt/mcp-server-tester-sse-http-stdio/discussions)
- Email: support@stgmt.dev
---
*Developed with β€οΈ by [@ii_pomogator](https://t.me/ii_pomogator)*
Raw data
{
"_id": null,
"home_page": null,
"name": "mcp-server-tester",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "mcp, model-context-protocol, testing, server-testing, sse, stdio, http, ai-tools, llm-tools",
"author": null,
"author_email": "stgmt <your-email@example.com>",
"download_url": "https://files.pythonhosted.org/packages/17/dc/7e0159b5e55284b705540d0298854427dc0f710713add692b2abd60a6d25/mcp_server_tester-1.4.3.tar.gz",
"platform": null,
"description": "[\ud83c\uddf7\ud83c\uddfa \u0420\u0443\u0441\u0441\u043a\u0430\u044f \u0432\u0435\u0440\u0441\u0438\u044f](./README.ru.md)\n\n# MCP Server Tester - High-performance testing framework for MCP servers with SSE-HTTP-STDIO protocol support, Bearer token authorization, and declarative test scenarios\n\nA 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.\n\n## \ud83d\ude80 Available on All Platforms\n\n[](https://www.npmjs.com/package/mcp-server-tester-sse-http-stdio)\n[](https://pypi.org/project/mcp-server-tester/)\n[](https://hub.docker.com/r/stgmt/mcp-server-tester)\n[](https://github.com/stgmt/mcp-server-tester-sse-http-stdio/actions)\n\n## \ud83d\udc68\u200d\ud83d\udcbb Author\n\nCreated by [**@ii_pomogator**](https://t.me/ii_pomogator) - AI Assistant Channel on Telegram\n\n---\n\n## \u2728 Key Features\n\n- \ud83d\udd0c **Full SSE-HTTP-STDIO protocol support** for MCP servers\n- \ud83d\udd10 **Bearer token authorization** for secure testing\n- \ud83d\udcdd **Declarative tests** - write scenarios in YAML without programming\n- \ud83c\udfaf **Multiple assertion types** - verify any aspects of responses\n- \ud83d\udcca **Detailed reports** on test execution\n- \ud83d\udc33 **Docker support** for isolated testing\n- \ud83d\udd04 **CI/CD integration** via GitHub Actions\n\n## \ud83d\udce6 Installation\n\n### NPM (Node.js)\n```bash\nnpm install -g mcp-server-tester-sse-http-stdio\n```\n\n### PyPI (Python)\n```bash\npip install mcp-server-tester\n```\n\n### Docker\n```bash\ndocker pull stgmt/mcp-server-tester\n```\n\n## \ud83d\ude80 Quick Start\n\n### Using NPM\n```bash\nnpx mcp-server-tester-sse-http-stdio test --test test.yaml --server-config config.json\n```\n\n### Using Python\n```bash\nmcp-server-tester test --test test.yaml --server-config config.json\n```\n\n### Using Docker\n```bash\ndocker run -v $(pwd):/workspace stgmt/mcp-server-tester test --test /workspace/test.yaml\n```\n\n## \ud83d\udcdd Example Test Scenario\n\n```yaml\nname: \"MCP Server Basic Test\"\ndescription: \"Testing basic MCP server functionality\"\ntimeout: 30000\n\ntests:\n - name: \"Initialize connection\"\n type: \"initialize\"\n params:\n protocolVersion: \"1.0.0\"\n capabilities:\n tools: true\n expect:\n status: \"success\"\n capabilities:\n tools: true\n\n - name: \"List available tools\"\n type: \"tools/list\"\n expect:\n status: \"success\"\n tools:\n - name: \"echo\"\n description: \"Echo tool\"\n\n - name: \"Call echo tool\"\n type: \"tools/call\"\n params:\n name: \"echo\"\n arguments:\n message: \"Hello, MCP!\"\n expect:\n status: \"success\"\n result:\n message: \"Hello, MCP!\"\n```\n\n## \ud83d\udccb Server Configuration\n\n```json\n{\n \"mcpServers\": {\n \"test-server\": {\n \"command\": \"node\",\n \"args\": [\"server.js\"],\n \"env\": {\n \"BEARER_TOKEN\": \"your-secret-token\"\n },\n \"transport\": {\n \"type\": \"sse\",\n \"config\": {\n \"url\": \"http://localhost:3000/sse\",\n \"headers\": {\n \"Authorization\": \"Bearer your-secret-token\"\n }\n }\n }\n }\n }\n}\n```\n\n## \ud83d\udee0\ufe0f CLI Commands\n\n### Run Tests\n```bash\nmcp-server-tester test --test <test-file> --server-config <config-file> [options]\n\nOptions:\n --server-name <name> Server name from configuration\n --verbose Verbose output\n --json-output Output results in JSON format\n --timeout <ms> Test timeout (default: 30000)\n```\n\n### Validate Configuration\n```bash\nmcp-server-tester validate --test <test-file>\n```\n\n### List Available Server Tools\n```bash\nmcp-server-tester tools --server-config <config-file> --server-name <name>\n```\n\n## \ud83d\udc33 Docker Support\n\n### Simple Run\n```bash\ndocker run -v $(pwd):/workspace stgmt/mcp-server-tester \\\n test --test /workspace/test.yaml --server-config /workspace/config.json\n```\n\n### Docker Compose\n```yaml\nversion: '3.8'\nservices:\n mcp-tester:\n image: stgmt/mcp-server-tester\n volumes:\n - ./tests:/workspace/tests\n - ./config:/workspace/config\n command: test --test /workspace/tests/test.yaml --server-config /workspace/config/server.json\n```\n\n### Supported Platforms\n| Platform | Architecture | Status |\n|----------|--------------|--------|\n| Linux | amd64 | \u2705 |\n| Linux | arm64 | \u2705 |\n| macOS | amd64 | \u2705 |\n| macOS | arm64 | \u2705 |\n| Windows | amd64 | \u2705 |\n\n## \ud83d\udd04 CI/CD Integration\n\n### GitHub Actions\n```yaml\nname: MCP Server Tests\non: [push, pull_request]\n\njobs:\n test:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v3\n \n - name: Run MCP Server Tests\n run: |\n docker run -v ${{ github.workspace }}:/workspace \\\n stgmt/mcp-server-tester test \\\n --test /workspace/tests/test.yaml \\\n --server-config /workspace/config.json\n```\n\n### GitLab CI\n```yaml\nmcp-tests:\n image: stgmt/mcp-server-tester\n script:\n - mcp-server-tester test --test tests/test.yaml --server-config config.json\n```\n\n## \ud83d\udcca Assertion Examples\n\n### Response Structure Validation\n```yaml\nexpect:\n status: \"success\"\n result:\n type: \"object\"\n properties:\n message:\n type: \"string\"\n pattern: \"^Hello.*\"\n count:\n type: \"number\"\n minimum: 0\n```\n\n### Array Validation\n```yaml\nexpect:\n tools:\n type: \"array\"\n minItems: 1\n items:\n type: \"object\"\n required: [\"name\", \"description\"]\n```\n\n### Conditional Validation\n```yaml\nexpect:\n oneOf:\n - status: \"success\"\n result: { processed: true }\n - status: \"pending\"\n result: { queued: true }\n```\n\n## \ud83d\udd27 Advanced Features\n\n### Environment Variables\n```yaml\ntests:\n - name: \"Test with env variables\"\n env:\n API_KEY: \"${TEST_API_KEY}\"\n BASE_URL: \"${TEST_BASE_URL:-http://localhost:3000}\"\n```\n\n### Sequential Tests with Dependencies\n```yaml\ntests:\n - name: \"Create resource\"\n id: \"create\"\n type: \"tools/call\"\n params:\n name: \"create_resource\"\n capture:\n resource_id: \"$.result.id\"\n \n - name: \"Get created resource\"\n depends_on: [\"create\"]\n type: \"tools/call\"\n params:\n name: \"get_resource\"\n arguments:\n id: \"${resource_id}\"\n```\n\n### Parallel Execution\n```yaml\nparallel_groups:\n - name: \"Performance tests\"\n tests:\n - name: \"Test 1\"\n - name: \"Test 2\"\n - name: \"Test 3\"\n```\n\n## \ud83d\udcda Documentation\n\n- [Complete Guide](https://github.com/stgmt/mcp-server-tester-sse-http-stdio/wiki)\n- [API Reference](https://github.com/stgmt/mcp-server-tester-sse-http-stdio/wiki/API)\n- [Test Examples](https://github.com/stgmt/mcp-server-tester-sse-http-stdio/tree/main/examples)\n- [FAQ](https://github.com/stgmt/mcp-server-tester-sse-http-stdio/wiki/FAQ)\n\n## \ud83e\udd1d Contributing\n\nWe welcome contributions to the project! See [CONTRIBUTING.md](CONTRIBUTING.md) for details.\n\n## \ud83d\udcc4 License\n\nMIT License - see [LICENSE](LICENSE) file.\n\n## \ud83d\udd17 Links\n\n- **GitHub**: [stgmt/mcp-server-tester-sse-http-stdio](https://github.com/stgmt/mcp-server-tester-sse-http-stdio)\n- **NPM**: [mcp-server-tester-sse-http-stdio](https://www.npmjs.com/package/mcp-server-tester-sse-http-stdio)\n- **PyPI**: [mcp-server-tester](https://pypi.org/project/mcp-server-tester/)\n- **Docker Hub**: [stgmt/mcp-server-tester](https://hub.docker.com/r/stgmt/mcp-server-tester)\n\n## \ud83d\udcac Support\n\n- [Create Issue](https://github.com/stgmt/mcp-server-tester-sse-http-stdio/issues)\n- [Discussions](https://github.com/stgmt/mcp-server-tester-sse-http-stdio/discussions)\n- Email: support@stgmt.dev\n\n---\n\n*Developed with \u2764\ufe0f by [@ii_pomogator](https://t.me/ii_pomogator)*\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python wrapper for mcp-server-tester-sse-http-stdio NPM package",
"version": "1.4.3",
"project_urls": {
"Bug Reports": "https://github.com/stgmt/mcp-server-tester-python/issues",
"Homepage": "https://github.com/stgmt/mcp-server-tester-python",
"NPM Package": "https://www.npmjs.com/package/mcp-server-tester-sse-http-stdio",
"Source": "https://github.com/stgmt/mcp-server-tester-python"
},
"split_keywords": [
"mcp",
" model-context-protocol",
" testing",
" server-testing",
" sse",
" stdio",
" http",
" ai-tools",
" llm-tools"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "5c48a97e19499a4ae94ad1da91fe069405a9e8b66c76424dc2995ca5ac09059a",
"md5": "cce914b5ea39f7412b9cd8c489a0f628",
"sha256": "705b8ca95fcfabeb29dbb6c8117441e2d21cb856aebfe20f930ea04c83ada290"
},
"downloads": -1,
"filename": "mcp_server_tester-1.4.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "cce914b5ea39f7412b9cd8c489a0f628",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 12895,
"upload_time": "2025-09-11T04:12:46",
"upload_time_iso_8601": "2025-09-11T04:12:46.236363Z",
"url": "https://files.pythonhosted.org/packages/5c/48/a97e19499a4ae94ad1da91fe069405a9e8b66c76424dc2995ca5ac09059a/mcp_server_tester-1.4.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "17dc7e0159b5e55284b705540d0298854427dc0f710713add692b2abd60a6d25",
"md5": "cb184595497c3a5732ebdbfe41451b44",
"sha256": "a02b4a56fada60e857c4ae5e12cde2a06cc5971da31fe6cf772bf29046880c56"
},
"downloads": -1,
"filename": "mcp_server_tester-1.4.3.tar.gz",
"has_sig": false,
"md5_digest": "cb184595497c3a5732ebdbfe41451b44",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 16963,
"upload_time": "2025-09-11T04:12:47",
"upload_time_iso_8601": "2025-09-11T04:12:47.492061Z",
"url": "https://files.pythonhosted.org/packages/17/dc/7e0159b5e55284b705540d0298854427dc0f710713add692b2abd60a6d25/mcp_server_tester-1.4.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-11 04:12:47",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "stgmt",
"github_project": "mcp-server-tester-python",
"github_not_found": true,
"lcname": "mcp-server-tester"
}
JSON
