@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	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.

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.