sitespeed-mcp-server by myanees284 - MCP Server

Sitespeed-MCP Server

A plug-and-play Sitespeed.io Model Context Protocol (MCP) server built using FastMCP.
It allows you to run performance tests and analyze Chrome traces directly from MCP-compatible clients such as
VS Code (GitHub Copilot MCP), Cline, or Claude Desktop.

Features

Tool	Description
`run_sitespeed`	Run a Sitespeed.io performance test for a given URL
`read_sitespeed_data`	Read and parse JSON metrics from a test run
`analyze_trace`	Extract long tasks (>50 ms) from Chrome traces
`analyze_network`	Summarize all network requests (total + unique)
`analyze_rendering`	Analyze paint/layout/compositing events
`analyze_memory`	Extract GC and memory events from trace data

Project Structure

.
├── app
│   ├── __init__.py
│   ├── main.py
│   └── services
│       └── runner.py
├── Dockerfile
├── requirements.txt
└── sitespeed-results

Build and Run with Docker

Build the image

docker build -t sitespeed-mcp-server .

Run the container

docker run --rm -i \
  -v $(pwd)/sitespeed-results:/app/sitespeed-results \
  sitespeed-mcp-server

All output will be stored under ./sitespeed-results on your host.

Environment Variables

Variable	Default	Purpose
`SITESPEED_OUTPUT`	`/app/sitespeed-results`	Output directory for test results
`PYTHONPATH`	`/app`	Python module path for FastMCP imports

Integration with MCP Clients

GitHub Copilot (MCP Agent Mode in VS Code)

Open Command Palette → “MCP: Add Server”
Use this configuration:

{
  "type": "stdio",
            "command": "docker",
            "args": [
                "run",
                "-i",
                "--rm",
                "-v",
                "./sitespeed-results:/app/sitespeed-results",
                "sitespeed-mcp-server"
            ],
            "env": {}
}

Save and reload VS Code.
Copilot Agent will detect and list all tools.

Claude Desktop / Cline

Edit your MCP config (for example ~/.config/Cline/config.json):

{
  "servers": {
        "sitespeed-mcp-server": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-v",
        "/<your local path>/sitespeed-results:/app/sitespeed-results",
        "sitespeed-mcp-server"
      ]
    }
}

Example Usage

Run a test:

/run_sitespeed https://www.amazon.com/

Read results:

/read_sitespeed_data run-20251007-163744

Analyze trace:

/analyze_trace run-20251007-163744

Development Notes

Base image → sitespeedio/sitespeed.io:38.3.0
Python runtime → includes fastmcp
Entrypoint → fastmcp run ./app/main.py
Communication → STDIO (no ports needed)
Logs → Sitespeed output streamed via MCP client

Troubleshooting

Issue	Cause	Fix
`File not found: /app/app.main`	Wrong ENTRYPOINT	Use `./app/main.py`
`Data folder not found: /app/sitespeed-results/sitespeed-results/...`	Duplicate path join	Use `os.path.join(BASE_DIR, run_id, "data")`
`Mounts denied` (macOS)	Docker path not shared	Add the path in Docker Desktop → Resources → File Sharing

Publish to Docker Hub

Tag and push

docker tag sitespeed-mcp-server <your repository name>/sitespeed-mcp-server:<your tag>
docker push <your repository name>/sitespeed-mcp-server:<your tag>

Pull and run

docker run --rm -i \
  -v $(pwd)/sitespeed-results:/app/sitespeed-results \
  <your repository name>/sitespeed-mcp-server

myanees284/sitespeed-mcp-server