@speedofme/mcp

@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 → Integrations → Generate Secret

Don't have an account? Register here

MCP Server Setup

Works with popular MCP clients:

• Claude Code / Claude Desktop / Cursor / Windsurf / Zed
• VS Code (Copilot) / Cline / Continue / JetBrains / Goose

Add to your MCP client config:

{
  "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!

Note: Some clients use different config formats. See full documentation for client-specific configs and agent framework examples (LangChain, LlamaIndex, AutoGen, CrewAI, Semantic Kernel).

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)
testTimeout	number	300	Overall cap for the whole run in seconds. 0 disables, min 30, max 1800

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.
--timeout <n>	Overall cap for the whole test in seconds, 0 disables (default: 300). Maps to testTimeout 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']
});

// Abort the ongoing test from elsewhere (e.g. a cancel action):
// the pending run() rejects with 'Speed test aborted'. No-op when idle.
test.abortTest();

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)
testTimeout	number	300	Overall wall clock cap for the whole run in seconds. On expiry run() rejects with Speed test timed out after Ns. 0 disables, min 30, max 1800
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: [e-mail]

License

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