@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

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	API secret (or set SOM_API_SECRET env var)
-p, --progress	Show progress during test
-j, --json	Output results as JSON
--tests	Tests to run: download,upload,latency (default: all)
--sustain	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	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.

License

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

SpeedOf.Me Speed Test MCP