mcp-rtcstats

An MCP (Model Context Protocol) server for analyzing WebRTC stats via rtcstats.com. Runs via stdio only; use with MCP clients like Cursor, Claude or any AI that connects to a MCP local server.

Project Structure

mcpMediaServer/
├── commands/          # Command definitions and handlers
│   ├── analyze-rtcstats.js
│   ├── hello-world.js
│   └── status.js
├── script/
│   └── upload-test.mjs   # Test script for /api/rtcstats/v1.0/mcp
├── utils/             # Utility functions
│   └── command-loader.js
├── index.js           # Main server entry point
├── test-mcp.sh        # JSON-RPC test flow
├── package.json
└── README.md

Features

• Modular Architecture: Each command has its own file in the commands/ directory
• Dynamic Loading: Commands are automatically loaded from the commands/ directory
• Easy Extension: Add new commands by creating files in commands/

Commands

hello-world

Returns "hello-world". Use to verify the MCP is working.

status

Health-check for the MCP. Returns {success: true} only when ANALYZER_API_KEY is correctly configured. Also returns the RTCStats API URL that will be used (from RTCSTATS_API_URL or default https://www.rtcstats.com). Agents can use this to verify the connection and configuration before calling other tools.

Response when healthy:

{
  "success": true,
  "rtcstatsUrl": "https://www.rtcstats.com",
  "tokenConfigured": true
}

Response when token missing:

{
  "success": false,
  "rtcstatsUrl": "https://www.rtcstats.com",
  "tokenConfigured": false
}

analyze-rtcstats

Upload a WebRTC dump file to rtcstats.com for analysis. Provide either a file path or the raw file content.

Parameters:

• filePath (optional): Path to the WebRTC dump file on disk (supports ~ for home)
• fileContent (optional): Raw file content (for JSON dumps when file is not on disk)

Provide either filePath OR fileContent.

Example (file path):

{
  "filePath": "~/Downloads/test_dump.json"
}

Example (file content):

{
  "fileContent": "{ \"stats\": [...] }"
}

Requires: ANALYZER_API_KEY in MCP config env (JWT from rtcstats.com Settings > Applications).

Installation

npm install -g mcp-rtcstats

When installed globally, the mcp-rtcstats command is available.

Usage

Add to your MCP client configuration (e.g. Cursor or Claude):

Production (defaults to https://www.rtcstats.com):

{
  "mcpServers": {
    "mcp-rtcstats": {
      "command": "mcp-rtcstats",
      "env": {
        "ANALYZER_API_KEY": "your_jwt_from_rtcstats_settings",
        "RTCSTATS_API_URL": "https://www.rtcstats.com"
      }
    }
  }
}

Test MCP API directly

To verify the API request format and token, run:

node script/upload-test.mjs "$ANALYZER_API_KEY" [filePath] [baseUrl]
# Example (production):
node script/upload-test.mjs "$ANALYZER_API_KEY" ./my-dump.json
# Example (local dev):
node script/upload-test.mjs "$ANALYZER_API_KEY" ./my-dump.json http://localhost:3000

The script sends the dump file to POST /api/rtcstats/v1.0/mcp.

Test MCP server

To run the MCP server through a basic JSON-RPC flow (initialize, tools/list, tools/call):

./test-mcp.sh

Requires ANALYZER_API_KEY for the analyze-rtcstats call. Uses test_dump if present, else minimal content.

Adding New Commands

To add a new command:

1. Create a new file in commands/ (e.g., commands/my-command.js):

import { z } from "zod";

export const toolDefinition = {
  name: "my-command",
  description: "Description of your command",
  inputSchema: {
    param1: z.string().describe("Parameter description"),
  },
};

export async function handler(args) {
  return {
    content: [{ type: "text", text: "Your response" }],
  };
}

2. The command will be automatically loaded when the server starts.

Installation

Claude

Use this command

claude mcp add mcp-rtcstats --env ANALYZER_API_KEY=<token> --env RTCSTATS_API_URL='https://staging.rtcstats.com' -- node /Users/oan/github/mcp-rtcstats/index.js

Publishing to Smithery

This server uses stdio transport and is compatible with Smithery Local publishing. Users discover and install it through Smithery, and it runs on their machine.

1. Publish to npm (if not already): npm publish --access public (for scoped packages)

2. Add to Smithery via web UI: Go to smithery.ai/new and add your npm package (e.g. @rtcstats/mcp-rtcstats). The CLI does not support stdio/npm publishing; use the web interface.

3. 403 Forbidden during validation? This package includes a static server card at .well-known/mcp/server-card.json so Smithery can extract metadata without scanning. If you still get 403 (e.g. from GitHub when Smithery fetches repo info), ensure your repo is public and accessible. See Smithery troubleshooting.

Smithery passes config as CLI args (--analyzer-api-key, --rtcstats-api-url). The server parses these and sets process.env accordingly, so it works with both Smithery and traditional env-based MCP configs.

License

MIT