MCP Server Tester

A dedicated MCP Server for testing other MCP Servers using STDIO mode, implemented in TypeScript.

Features

Connection Testing: Verify basic connection and initialization of target MCP Servers
Capability Discovery: Automatically discover and list all tools, resources, and prompts
Tool Call Testing: Test specific tools to ensure they work correctly
Clear Test Reports: Display testing process and results in a structured, readable format

Installation

Using npx (Recommended)

You can run MCP Tester directly from GitHub without installation:

npx github:Peterpan-MU/MCP-Test

Local Installation

# Clone the repository
git clone https://github.com/Peterpan-MU/MCP-Test.git
cd MCP-Test

# Install dependencies
npm install

# Build the project
npm run build

Usage

Method 1: As a Standalone MCP Server

Configure this server in your MCP client (e.g., Claude Desktop):

Option A: Direct from GitHub (Recommended)

{
  "mcpServers": {
    "mcp-tester": {
      "command": "npx",
      "args": ["-y", "github:Peterpan-MU/MCP-Test"]
    }
  }
}

Option B: Using package name (after local install)

# First, install globally or link locally
npm install -g github:Peterpan-MU/MCP-Test
# or
cd MCP-Test && npm link

Then configure:

{
  "mcpServers": {
    "mcp-tester": {
      "command": "npx",
      "args": ["mcp-server-tester"]
    }
  }
}

Option C: Local development

{
  "mcpServers": {
    "mcp-tester": {
      "command": "node",
      "args": ["E:\\MCP Test\\dist\\index.js"]
    }
  }
}

Then call the testing tools from your MCP client.

Method 2: Run Tests Directly

# If installed locally
npm test

# Or run directly with npx
git clone https://github.com/Peterpan-MU/MCP-Test.git
cd MCP-Test
npm install
npm test

Available Tools

1. test_server_connection

Test basic connection capabilities of a target MCP Server.

Parameters:

command (string): Launch command, e.g., "node", "python", "uvx"
args (array): Command arguments, e.g., ["server.js"]
env (object, optional): Environment variables

Example:

{
  "command": "node",
  "args": ["/path/to/your_server.js"],
  "env": {
    "API_KEY": "your_key"
  }
}

Output: Detailed connection test report including:

Connection status
Initialization result
Test process steps

2. test_server_capabilities

Comprehensively test all capabilities of a target MCP Server.

Parameters:

command (string): Launch command
args (array): Command arguments
env (object, optional): Environment variables

Example:

{
  "command": "node",
  "args": ["/path/to/your_server.js"]
}

Output: Complete capability report including:

List of all available tools with descriptions
List of all available resources
List of all available prompts
Statistics for each capability type

3. test_tool_call

Test calling a specific tool on the target MCP Server.

Parameters:

command (string): Launch command
args (array): Command arguments
env (object, optional): Environment variables
test_tool (string): Tool name to test
tool_arguments (object, optional): Arguments to pass to the tool

Example:

{
  "command": "node",
  "args": ["/path/to/your_server.js"],
  "test_tool": "echo",
  "tool_arguments": {
    "message": "Hello, MCP!"
  }
}

Output: Tool call test report including:

Whether the call succeeded
Returned content
Whether an error occurred

Testing Examples

Example 1: Test a Simple Node.js MCP Server

Assuming you have an MCP server named simple_server.js:

Connection Test:

{
  "command": "node",
  "args": ["/servers/simple_server.js"]
}

Capability Test:

{
  "command": "node",
  "args": ["/servers/simple_server.js"]
}

Tool Call Test (assuming the server has a "get_time" tool):

{
  "command": "node",
  "args": ["/servers/simple_server.js"],
  "test_tool": "get_time",
  "tool_arguments": {}
}

Example 2: Test a Python MCP Server

{
  "command": "python",
  "args": ["/servers/python_server.py"]
}

Example 3: Test an MCP Server Installed via uvx

{
  "command": "uvx",
  "args": ["mcp-server-time"]
}

Sample Test Report

Connection Test Report

============================================================
🧪 MCP Server 连接测试报告
============================================================

📋 测试配置:
  命令: node
  参数: server.js

🔄 测试过程:
  🔌 正在连接到目标MCP Server...
  ✅ 连接初始化成功
  ✅ 基本连接测试通过
  🎉 所有测试步骤完成

✅ 测试结果: 成功
  状态: connected
  消息: 目标服务器成功响应初始化请求

============================================================

Capability Test Report

============================================================
🧪 MCP Server 能力测试报告
============================================================

📋 测试配置:
  命令: node
  参数: server.js

🔄 测试过程:
  🔌 正在连接到目标MCP Server...
  ✅ 连接初始化成功
  🔍 正在获取服务器能力...
  📦 发现 3 个工具
  📚 发现 0 个资源
  💬 发现 0 个提示词
  ✅ 能力测试完成
  🎉 所有测试步骤完成

✅ 测试结果: 成功

📦 工具列表 (3):
  1. echo
     描述: Echo back the provided message
  2. add
     描述: Add two numbers together
  3. get_time
     描述: Get current time

📚 资源列表 (0):
  (无资源或不支持)

💬 提示词列表 (0):
  (无提示词或不支持)

============================================================

Configuration File

Refer to test_config_example.json for how to configure multiple test servers and test scenarios.

Troubleshooting

Issue: MCP error -32000: Connection closed

This error usually means the MCP client cannot establish a connection with the server.

Solutions:

Try using Option C (local path):

{
  "mcpServers": {
    "mcp-tester": {
      "command": "node",
      "args": ["E:\\MCP Test\\dist\\index.js"]
    }
  }
}

Verify npx can find the package:

npx -y github:Peterpan-MU/MCP-Test

Then type a test JSON-RPC request:

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}

Check Node.js version:
```
node --version  # Should be >= 18.0.0
```

Try clearing npx cache:

npx clear-npx-cache
# or
rm -rf ~/.npm/_npx

Install locally first:
```
npm install -g github:Peterpan-MU/MCP-Test
```
Then use "args": ["mcp-server-tester"] in config

Issue: Connection Timeout (-32001)

Solution:

Ensure the latest version is installed (dist/ files are pre-built, no compilation needed)
Check network connection if using npx with GitHub URL
Try local installation option

Issue: Tool Call Failed

Solution:

Use test_server_capabilities to first view available tools
Check if tool parameters are correct
Verify the target server path and dependencies

Issue: Import Errors

Solution:

cd "E:\MCP Test"
npm install
npm run build

Technical Details

Transport Mode: STDIO (standard input/output)
Language: TypeScript
Runtime: Node.js 18+
MCP SDK Version: 1.0.4+
Concurrency Model: Async/await with Promises

Project Structure

MCP-Test/
├── src/
│   ├── index.ts              # Main MCP Tester server
│   ├── tester.ts             # Testing logic implementation
│   ├── example-server.ts     # Example server for testing
│   └── test.ts               # Test runner script
├── dist/                     # Compiled JavaScript (generated)
├── package.json              # NPM package configuration
├── tsconfig.json             # TypeScript configuration
├── requirements.txt          # Python dependencies (legacy)
├── README.md                 # This file
├── LICENSE                   # MIT License
├── .gitignore               # Git ignore rules
└── test_config_example.json # Configuration examples

Development

Build the Project

npm run build

Watch Mode (Development)

npm run dev

Run Tests

npm test

Publishing to npm (Optional)

To publish this package to npm for easier access:

# Login to npm (first time only)
npm login

# Publish the package
npm publish

After publishing, users can run:

npx mcp-server-tester

Name		Name	Last commit message	Last commit date
Latest commit History 6 Commits
dist		dist
src		src
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
example_server.py		example_server.py
mcp_tester.py		mcp_tester.py
package.json		package.json
requirements.txt		requirements.txt
run_tests.py		run_tests.py
test_as_client.js		test_as_client.js
test_config_example.json		test_config_example.json
test_mcp_connection.js		test_mcp_connection.js
test_mcp_full.js		test_mcp_full.js
tsconfig.json		tsconfig.json

License

Peterpan-MU/MCP-Test

Folders and files

Latest commit

History

Repository files navigation

MCP Server Tester

Features

Installation

Using npx (Recommended)

Local Installation

Usage

Method 1: As a Standalone MCP Server

Method 2: Run Tests Directly

Available Tools

1. test_server_connection

2. test_server_capabilities

3. test_tool_call

Testing Examples

Example 1: Test a Simple Node.js MCP Server

Example 2: Test a Python MCP Server

Example 3: Test an MCP Server Installed via uvx

Sample Test Report

Connection Test Report

Capability Test Report

Configuration File

Troubleshooting

Issue: MCP error -32000: Connection closed

Issue: Connection Timeout (-32001)

Issue: Tool Call Failed

Issue: Import Errors

Technical Details

Project Structure

Development

Build the Project

Watch Mode (Development)

Run Tests

Publishing to npm (Optional)

License

Contributing

Related Resources

Changelog

Version 1.0.0 (TypeScript)

Version 0.1.0 (Python - Legacy)

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Contributors 2

Uh oh!

Languages

Packages