MCP Test

🚀 MCP Server Tester

The MCP Server Tester is a specialized tool crafted in TypeScript. It leverages the STDIO mode to conduct comprehensive tests on other MCP Servers, ensuring their reliability and functionality.

✨ Features

• Connection Testing: Validate the fundamental connection and initialization of target MCP Servers.
• Capability Discovery: Automatically detect and enumerate all available tools, resources, and prompts.
• Tool Call Testing: Verify the correct operation of specific tools.
• Clear Test Reports: Present test processes and results in a structured and easily readable format.

📦 Installation

Using npx (Recommended)

You can directly run the MCP Tester 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 Examples

Basic 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

Advanced Usage

Available Tools

• test_server_connection: Test the basic connection capabilities of a target MCP Server.

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

Output: A detailed connection test report including connection status, initialization result, and test process steps.

• test_server_capabilities: Comprehensively test all capabilities of a target MCP Server.

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

Output: A complete capability report including a list of all available tools with descriptions, a list of all available resources, a list of all available prompts, and statistics for each capability type.

• test_tool_call: Test calling a specific tool on the target MCP Server.

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

Output: A tool call test report including whether the call succeeded, the returned content, and whether an error occurred.

Testing Examples

• Example 1: Test a Simple Node.js MCP Server
  • 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"]
}

📚 Documentation

Sample Test Report

Connection Test Report

============================================================
🧪 MCP Server Connection Test Report
============================================================

📋 Test Configuration:
  Command: node
  Arguments: server.js

🔄 Test Process:
  🔌 Connecting to the target MCP Server...
  ✅ Connection initialization successful
  ✅ Basic connection test passed
  🎉 All test steps completed

✅ Test Result: Success
  Status: connected
  Message: The target server successfully responded to the initialization request

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

Capability Test Report

============================================================
🧪 MCP Server Capability Test Report
============================================================

📋 Test Configuration:
  Command: node
  Arguments: server.js

🔄 Test Process:
  🔌 Connecting to the target MCP Server...
  ✅ Connection initialization successful
  🔍 Retrieving server capabilities...
  📦 3 tools found
  📚 0 resources found
  💬 0 prompts found
  ✅ Capability test completed
  🎉 All test steps completed

✅ Test Result: Success

📦 Tool List (3):
  1. echo
     Description: Echo back the provided message
  2. add
     Description: Add two numbers together
  3. get_time
     Description: Get current time

📚 Resource List (0):
  (No resources or not supported)

💬 Prompt List (0):
  (No prompts or not supported)

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

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
  • 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

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

This project is under the MIT License. See the 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 the Node.js ecosystem.

Version 0.1.0 (Python - Legacy)

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