mcp-reporter connects to local stdio processes and remote Streamable HTTP endpoints, reads their advertised capabilities, and writes a report you can keep alongside project documentation or pass to another tool.

It enumerates tools, resources, resource templates, and prompts. It does not execute tools, read resource contents, or expand prompts. View a synthetic example report.

Quick start

Requires Node.js 22.12 or newer. Development uses Bun 1.4 or newer.

Create mcp-servers.json with a server you already run:

{
  "mcpServers": {
    "local-server": {
      "command": "node",
      "args": ["/absolute/path/to/server/dist/index.js"]
    }
  }
}

Generate a report:

npx mcp-reporter --config mcp-servers.json --output output/report.md

Configuration

The configuration is a JSON object containing mcpServers. Each key identifies a server in the report. Local and remote entries can share one file:

{
  "mcpServers": {
    "local-server": {
      "command": "node",
      "args": ["/absolute/path/to/server/dist/index.js"],
      "env": { "EXAMPLE_API_KEY": "REPLACE_WITH_YOUR_KEY" }
    },
    "remote-server": {
      "type": "http",
      "url": "https://example.com/mcp",
      "headers": { "Authorization": "Bearer REPLACE_WITH_YOUR_TOKEN" }
    },
    "disabled-server": {
      "command": "node",
      "args": ["/absolute/path/to/another/server.js"],
      "disabled": true
    }
  }
}

Supply exactly one of command or url. The reporter validates the entire file before connecting. Paths are resolved from the process working directory; use absolute paths when sharing a configuration between callers. Interactive OAuth and legacy SSE endpoints are not supported.

Configuration values can contain credentials. The reporter omits env/header values, raw command arguments, and URL paths/query/userinfo from its diagnostics and launch metadata. Child stderr is suppressed; failures use safe error categories. Server-provided descriptions, schemas, instructions, and extension metadata are retained as report content, so review those before sharing a report.

Choose a protocol mode

Legacy negotiation is the default, preserving compatibility with servers that expect initialize.

npx mcp-reporter --config mcp-servers.json --protocol-era auto

Auto mode can start an extra short-lived stdio process and wait for a probe timeout before using the legacy handshake. HTTP authorization failures and timeouts are reported as failures, not evidence of legacy support. The report records the actual selected protocol version and era.

Report contents

Lists are collected page by page. Each capability is reported as not advertised, complete (possibly empty), or incomplete. Page limits, repeated cursors and request failures keep collected entries and mark their counts as partial. A failed server or list does not discard successful neighbors.

Tables and text carry the report; collapsible details hold longer definitions. Icons remain metadata rather than remote image loads. Server annotations are hints supplied by the server, not independently verified safety guarantees. Enumeration retains advertisements even when a client might refuse to call a tool with an invalid schema extension.

CLI options

Existing positive flags -s/--schemas, -m/--metadata, and -e/--examples remain accepted. MCP enumeration has no examples source; examples appear only when a programmatic caller supplies them to the renderer.

Progress goes to stderr, and the report is written to the selected file. Exit code 0 means the report was written, including any recorded connection/list failures. Invalid configuration or a report-write failure exits 1.

Use as a library

bun add mcp-reporter

import { McpReporter } from 'mcp-reporter';

const reporter = new McpReporter('./mcp-servers.json', {
  outputPath: './output/capabilities.md',
  protocolEra: 'auto',
  includeInputSchemas: true,
  includeServerMetadata: true,
  maxPages: 64,
  timeoutMs: 30_000,
  progressCallback(event) {
    console.error(event.message);
  },
});

await reporter.run();

The library is ESM and stays quiet without a progress callback. run() resolves after writing the report and closing connections; it rejects configuration/file errors. A second run starts a fresh collection. ReportOptions.transportFactory(config, serverId) can supply a transport for embedding or deterministic tests.

Types are exported from the package root. To render an already collected ServerReport[], import MarkdownGenerator from mcp-reporter and call generateReport(reports, options). It honors the same rendering flags and preserves optional ToolInfo.examples supplied by the caller.

See upgrading to 1.1.0 for runtime, module, and reporting changes.

Development

Build a source checkout:

git clone https://github.com/cyanheads/mcp-reporter.git
cd mcp-reporter
bun install
bun run rebuild

Run the built CLI with node dist/cli.js --config mcp-servers.json.

Tests use in-memory SDK servers, loopback HTTP and synthetic stdio processes. They need no credentials or external MCP servers. Release workflows use local gates, per-version changelogs, conventional commits and annotated tag digests; npm and GitHub are the publication targets.

Contributing · Security · Changelog · Apache-2.0 license