English | 中文

mcp-smoke-test

mcp-smoke-test is a zero-dependency Node CLI that checks whether a stdio MCP server can start, answer initialize, and handle one basic follow-up probe.

If you need a fast answer to "does this MCP server actually initialize and interoperate?", this repo is the shortest path.

Quick Proof

• Runs over stdio with no runtime dependencies.
• Checks initialize, sends notifications/initialized, and attempts one real probe.
• Supports both direct command mode and config-driven mode.
• Ships with a local fake MCP fixture for reproducible tests.

What it does

• Starts an MCP server over stdio
• Sends a JSON-RPC initialize request
• Sends notifications/initialized
• Probes one advertised capability: tools/list, resources/list, or prompts/list
• Exits 0 on success and nonzero on failure
• Prints either human-readable text or JSON

Requirements

• Node.js >=20
• No runtime dependencies

Install

npm install

Demo

• Social preview: docs/assets/social-preview.png
• Terminal demo: docs/assets/demo-terminal.png
• Animated demo: docs/assets/demo.gif

Usage

Command mode

Run a server command directly.

node bin/mcp-smoke-test.js \
  --command node \
  --arg test/fixtures/fake-mcp-server.js \
  --format text

You can repeat --arg for additional arguments.

Config mode

Load one named server from a JSON MCP config file.

node bin/mcp-smoke-test.js \
  --config examples/mcp.config.json \
  --server fake-fixture \
  --format json

The CLI currently reads server entries from either mcpServers or servers.

Example config

See examples/mcp.config.json.

{
  "mcpServers": {
    "fake-fixture": {
      "command": "node",
      "args": ["../test/fixtures/fake-mcp-server.js"]
    }
  }
}

Output

Text mode example:

Smoke test passed
mode: command
command: node
initialize: ok (fake-mcp-server@1.0.0)
tools/list: ok (1 tool)

JSON mode example:

{
  "ok": true,
  "mode": "command",
  "server": {
    "command": "node",
    "args": ["test/fixtures/fake-mcp-server.js"]
  },
  "initialize": {
    "serverName": "fake-mcp-server",
    "serverVersion": "1.0.0"
  },
  "probe": {
    "attempted": true,
    "ok": true,
    "method": "tools/list",
    "summary": "1 tool"
  }
}

Development

Run the tests:

npm test

Repository docs

• Release notes: v0.1.0
• Contributing
• Security policy
• Support
• Code of conduct

Related repos

• mcp-saas-foundry for a production-minded MCP starter blueprint
• safe-mcp-config for config risk scanning before sharing examples
• ToolmeshAI for the broader portfolio around MCP and agent tooling

License

MIT. See LICENSE.