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:

1. Connection Test:

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

2. Capability Test:

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

3. 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:

1. Try using Option C (local path):

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

2. 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"}}}
   

3. Check Node.js version:

   node --version  # Should be >= 18.0.0
   

4. Try clearing npx cache:

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

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

License

MIT License - see LICENSE file for details.

Contributing

Issues and Pull Requests are welcome!

Related Resources

• MCP Official Documentation
• MCP TypeScript SDK
• MCP Server List

Changelog

Version 1.0.0 (TypeScript)

• Complete rewrite in TypeScript
• Support for npx installation
• Improved type safety and error handling
• Better integration with Node.js ecosystem

Version 0.1.0 (Python - Legacy)

• Initial Python implementation
• Basic testing capabilities
• STDIO mode support