@speedofme/mcp

SpeedOf.Me MCP Server - Run accurate internet speed tests from AI agents. Also works as CLI and SDK.

Quick Start

# Run speed test (no install)
SOM_API_SECRET=SOM_SECRET_xxx npx -y @speedofme/mcp --progress

# JSON output (for scripts)
SOM_API_SECRET=SOM_SECRET_xxx npx -y @speedofme/mcp --json

# Or install globally
npm i -g @speedofme/mcp
SOM_API_SECRET=SOM_SECRET_xxx speedofme --progress

# Windows
set SOM_API_SECRET=SOM_SECRET_xxx && npx -y @speedofme/mcp --progress

Get your free API secret: Register here

Features

• MCP Server: Model Context Protocol server for AI agent integration (Claude, etc.)
• CLI: Command-line tool for quick speed tests
• SDK: Promise-based API for running speed tests programmatically
• Local History: Stores test results in ~/.speedofme/history.json
• Analytics Dashboard: View detailed usage reports with device and geo breakdowns at speedof.me/api/portal

Requirements

• Node.js 18+
• SpeedOf.Me API account with API Secret

Getting Your API Secret

Log in → API Settings → Generate Secret

Don't have an account? Register here

MCP Server Setup

Add to your MCP client config (Claude Code, Claude Desktop, Cursor, Windsurf, etc.):

{
  "mcpServers": {
    "speedofme": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@speedofme/mcp"],
      "env": {
        "SOM_API_SECRET": "SOM_SECRET_xxx"
      }
    }
  }
}

Restart your MCP client, then ask the AI to run a speed test!

Available MCP Tools

| Tool | Description | |------|-------------| | run_speed_test | Run speed test with optional params | | get_test_history | Get historical test results |

run_speed_test Parameters

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | tests | string[] | all | Tests to run: download, upload, latency | | sustainTime | number | 6 | Seconds per sample (1-8) |

Example Response

{
  "testId": "abc123",
  "download": 150.5,
  "upload": 45.2,
  "latency": 12,
  "jitter": 2.3,
  "testServer": "San Jose",
  "timestamp": "2025-01-15T10:30:00Z"
}

Available MCP Resources

| Resource | Description | |----------|-------------| | speedofme://history | Recent test results (JSON) | | speedofme://config | SDK configuration and status |

CLI Usage

Run speed tests from the command line.

• npx: npx -y @speedofme/mcp [options]
• Global install: speedofme [options]

# Set your API secret
export SOM_API_SECRET=SOM_SECRET_xxx

# Run speed test with progress
npx -y @speedofme/mcp --progress

# Run specific tests only
npx -y @speedofme/mcp --tests download,latency

# Adjust sustain time (1-8 seconds, default: 6)
npx -y @speedofme/mcp --sustain 4

# View test history
npx -y @speedofme/mcp history
npx -y @speedofme/mcp history --limit 5

# Clear history
npx -y @speedofme/mcp history --clear

# Help and version
npx -y @speedofme/mcp --help
npx -y @speedofme/mcp --version

CLI Options

| Option | Description | |--------|-------------| | --secret <secret> | API secret (or set SOM_API_SECRET env var) | | -p, --progress | Show progress during test | | -j, --json | Output results as JSON | | --tests <list> | Tests to run: download,upload,latency (default: all) | | --sustain <n> | Sustain time per sample 1-8 seconds (default: 6). Maps to sustainTime in SDK/MCP. | | -h, --help | Show help | | -v, --version | Show version |

History Subcommand Options

| Option | Description | |--------|-------------| | --limit <n> | Number of results to show (default: 10) | | --clear | Clear all history |

SDK Usage

const { SpeedTest } = require('@speedofme/mcp');

const test = new SpeedTest({
  apiSecret: process.env.SOM_API_SECRET,
  sustainTime: 6  // optional, 1-8 seconds
});

// Progress callback (optional)
test.onProgress = (progress) => {
  console.log(progress);
};

// Run full test
const result = await test.run();
console.log(result);
// {
//   testId: 'uuid',
//   download: 150.5,      // Mbps
//   upload: 45.2,         // Mbps
//   latency: 12,          // ms
//   jitter: 2.3,          // ms
//   testServer: 'San Jose',
//   timestamp: '2025-01-15T10:30:00Z'
// }

// Run specific tests only
const downloadOnly = await test.run({
  tests: ['download']
});

// Run latency-only test (fastest)
const latencyOnly = await test.run({
  tests: ['latency']
});

Installation (Optional)

Install globally for frequent use:

npm install -g @speedofme/mcp

Or add to your project:

npm install @speedofme/mcp

History Management

const { getHistory, clearHistory } = require('@speedofme/mcp');

// Get recent results
const history = getHistory({ limit: 10 });

// Get results from last 7 days
const recent = getHistory({
  since: new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString()
});

// Clear all history
clearHistory();

History is stored in ~/.speedofme/history.json with a 1MB cap (~2,600 results).

Configuration Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | apiSecret | string | (required) | API secret from portal | | sustainTime | number | 6 | Seconds to sustain each sample (1-8). Lower = faster, higher = more accurate | | supportGbTest | boolean | false | Enable gigabit test mode | | maxTestPass | number | 0 | Max download passes (0 = no limit) | | saveHistory | boolean | true | Save results to local history |

Analytics Dashboard

All test results are automatically sent to your SpeedOf.Me dashboard where you can:

• View usage statistics over time
• See geographic distribution of tests
• Analyze device and platform breakdowns
• Monitor API usage against your plan limits

Visit speedof.me/api/portal to access your dashboard.

Links

• Get Started
• API Portal
• How It Works
• API Docs
• Status
• Email: [email protected]

License

This package is proprietary software. Unauthorized use, copying, or distribution is prohibited.