MCP Client Tester

A generic MCP (Model Context Protocol) client tool designed to help developers and security professionals test MCP servers for vulnerabilities. This tool can connect to MCP servers, list available tools, and provide information about server configurations.

Features

• 🔌 Connect to MCP servers via configuration file
• 📋 List all available tools from MCP servers
• 🔧 Call and execute tools on MCP servers
• 🔍 Get detailed server information
• 🛡️ Security-focused design for vulnerability testing
• 📊 JSON output support for automation
• 🔄 Support for multiple transport types (stdio, SSE, HTTP/HTTPS)

Installation

Install Globally (Recommended)

npm install -g mcp-client-tester

After installation, the mcp-client command will be available globally:

mcp-client list
mcp-client servers
mcp-client info <server-name>
mcp-client call <server-name> <tool-name>

Install Locally for Development

git clone <repository-url>
cd cursor-mcp-client
npm install

Then use via npm scripts or run directly:

# Via npm scripts
npm start -- list

# Or run directly
node src/cli.js list

Requirements

• Node.js >= 18.0.0
• npm >= 9.0.0

Configuration

Create an MCPserver.json file in your project root (or specify a custom path using the --config option). The configuration format follows the MCP standard:

{
  "mcpServers": {
    "example-server": {
      "command": "npx",
      "args": ["-y", "@example/mcp-server"],
      "env": {
        "API_KEY": "your-api-key"
      }
    },
    "sse-server": {
      "transport": "sse",
      "url": "http://localhost:3000/sse"
    },
    "http-server": {
      "transport": "http",
      "url": "https://api.example.com/mcp",
      "apiKey": "your-api-key-here"
    },
    "http-server-with-headers": {
      "transport": "http",
      "url": "https://api.example.com/mcp",
      "http": {
        "headers": {
          "Authorization": "Bearer your-token-here",
          "X-Custom-Header": "value"
        }
      }
    },
    "oauth-server": {
      "transport": "http",
      "url": "https://api.example.com/mcp",
      "oauth": {
        "clientId": "your-client-id",
        "clientSecret": "your-client-secret",
        "redirectUrl": "http://localhost:8080/callback",
        "tokenEndpointAuthMethod": "client_secret_basic",
        "grantTypes": ["authorization_code"],
        "responseTypes": ["code"]
      }
    }
  }
}

Configuration Options

• command: The command to run the server (e.g., "node", "npx", "python")
• args: Array of arguments to pass to the command
• env: Environment variables to set for the server process
• transport: Transport type ("stdio" default, "sse" for Server-Sent Events, "http" or "https" for HTTP/HTTPS)
• url: URL for SSE or HTTP transports
• apiKey: API key for HTTP transport (will be added as Authorization: Bearer <apiKey> header)
• http: HTTP-specific configuration object:
  • headers: Custom HTTP headers to include in requests
• oauth: OAuth 2.0 configuration object (for HTTP/HTTPS transports):
  • clientId: OAuth client ID
  • clientSecret: OAuth client secret
  • redirectUrl: OAuth redirect URL (must match server configuration)
  • tokenEndpointAuthMethod: Authentication method (default: "client_secret_basic")
  • grantTypes: OAuth grant types (default: ["authorization_code"])
  • responseTypes: OAuth response types (default: ["code"])
  • tokenFile: Optional path to store tokens (default: .mcp-tokens/<server-name>.json)

Usage

List all tools from all servers

# Using npm (note: use -- to pass flags through npm)
npm start -- list
# or run directly
node src/cli.js list

List tools from a specific server

npm start -- list --server example-server
# or
node src/cli.js list --server example-server

List all configured servers

npm start -- servers
# or
node src/cli.js servers

Get server information

npm start -- info example-server
# or
node src/cli.js info example-server

OAuth Authorization

For servers that require OAuth authentication:

# Attempt to connect (will show authorization URL if needed)
mcp-client list --server oauth-server

# Complete authorization with the code from the callback URL
mcp-client auth oauth-server --code <authorization-code>
# or
node src/cli.js auth oauth-server --code <authorization-code>

OAuth Flow:

1. Configure OAuth settings in your MCPserver.json
2. Try to connect to the server (e.g., mcp-client list --server oauth-server)
3. The tool will display an authorization URL
4. Open the URL in your browser and complete authorization
5. Copy the authorization code from the callback URL
6. Run mcp-client auth <server-name> --code <code> to complete the flow
7. Tokens are automatically saved and refreshed as needed

Generate tool call template

Generate a template command and example arguments for calling a tool:

# Generate JSON template with example arguments
npm start -- generate example-server tool-name
# or
node src/cli.js generate example-server tool-name

# Generate as a ready-to-use command
npm start -- generate example-server tool-name --command
# or
node src/cli.js generate example-server tool-name --command

# Generate and save arguments to a file
npm start -- generate example-server tool-name --file
# or
node src/cli.js generate example-server tool-name --file

This command will:

• Show the tool's description and parameters
• Generate example arguments based on the tool's input schema
• Provide a ready-to-use command or JSON template

Call a tool

Execute a tool on an MCP server. You can pass arguments as a JSON string or from a file:

# Call a tool with inline JSON arguments
npm start -- call example-server tool-name --args '{"param1":"value1","param2":"value2"}'
# or
node src/cli.js call example-server tool-name --args '{"param1":"value1","param2":"value2"}'

# Call a tool with arguments from a file
npm start -- call example-server tool-name --args-file ./args.json
# or
node src/cli.js call example-server tool-name --args-file ./args.json

# Call a tool without arguments
npm start -- call example-server tool-name
# or
node src/cli.js call example-server tool-name

Example arguments file (args.json):

{
  "account_id": "123",
  "limit": 10,
  "include_body": true
}

Tip: Use generate first to create a template, then modify it and use it with call!

JSON output

Add the --json flag to any command for machine-readable output:

npm start -- list --json
npm start -- list --server example-server --json
# or
node src/cli.js list --json

Custom configuration file

You can specify a custom configuration file path using the --config option. The path can be absolute or relative to the current working directory:

# Using npm - IMPORTANT: Use -- to pass flags through npm
npm start -- list --config ./configs/my-servers.json
npm start -- list --config /Users/username/configs/MCPserver.json

# Running directly (no -- needed)
node src/cli.js list --config ./configs/my-servers.json
node src/cli.js list --config /Users/username/configs/MCPserver.json

# Paths with spaces MUST be quoted
node src/cli.js list --config "/Users/username/Application Support/config.json"
node src/cli.js list --config '/Users/username/Application Support/config.json'

# The config option is global, so it works with all commands
npm start -- servers --config /path/to/config.json
npm start -- info example-server --config /path/to/config.json

Important:

• When using npm start, you must use -- before your flags to pass them through to the script. For example:
  • ✅ npm start -- list --config /path/to/config.json
  • ❌ npm start list --config /path/to/config.json (npm will intercept the flag)
• Paths with spaces must be quoted with single or double quotes:
  • ✅ --config "/path/with spaces/config.json"
  • ❌ --config /path/with spaces/config.json (will be split at the space)

Note: The --config option is global and applies to all commands. If not specified, it defaults to MCPserver.json in the current working directory.

Examples

Basic usage

# List all tools
npm start -- list
# or
node src/cli.js list

# Output:
# 📋 Server: example-server
#    Status: ✅ Connected
#    Tools: 5
#    
#    Available Tools:
#      1. tool1
#         Description of tool1
#      2. tool2
#         Description of tool2

Security testing workflow

1. Identify configured servers:

   npm start -- servers
   # or
   node src/cli.js servers
   

2. List all available tools:

   npm start -- list
   # or
   node src/cli.js list
   

3. Get detailed server information:

   npm start -- info example-server
   # or
   node src/cli.js info example-server
   

4. Export tool list for analysis:

   npm start -- list --json > tools.json
   # or
   node src/cli.js list --json > tools.json
   

5. Generate tool call templates:

   # Generate a template for a specific tool
   npm start -- generate example-server list_emails_metadata
   # or
   node src/cli.js generate example-server list_emails_metadata
   
   # Generate and save to file
   node src/cli.js generate example-server list_emails_metadata --file
   

6. Test tool execution:

   # Test a tool with arguments (use generate first to get the template)
   npm start -- call example-server list_emails_metadata --args '{"account_id":"test","limit":5}'
   # or
   node src/cli.js call example-server list_emails_metadata --args '{"account_id":"test","limit":5}'
   
   # Or use the generated file
   node src/cli.js call example-server list_emails_metadata --args-file list_emails_metadata_args.json
   

Security Considerations

This tool is designed to help security professionals:

• Tool Enumeration: Quickly identify all available tools in MCP servers
• Configuration Analysis: Review server configurations for potential vulnerabilities
• Transport Security: Test different transport mechanisms (stdio, SSE, HTTP/HTTPS)
• Automation: JSON output enables integration with security scanning tools
• Template Generation: Generate tool call templates for systematic testing

Troubleshooting

Server Warnings

Some MCP servers (particularly Python-based servers like Semgrep) may display warnings when connections are closed, such as:

WARNING Loop <_UnixSelectorEventLoop running=False closed=True> that handles pid X is closed

These warnings are harmless and come from the server process itself, not from this client. They occur when the server's event loop is being cleaned up and can be safely ignored.

Connection Issues

If a server fails to connect:

• Check that the server command is available in your PATH
• Verify the server configuration in your MCPserver.json file
• Ensure required environment variables are set
• Check server logs for more detailed error messages

License

MIT

Contributing

See CONTRIBUTING.md for development and contribution guidelines.