Akamai Traffic MCP

An MCP server that lets an AI assistant (Claude Code, Claude Desktop, or any MCP client) query Akamai Reporting API v2 traffic data for your own Akamai account, using your own EdgeGrid API credentials.

Ask things like "Which hostnames had the most edge hits last week?" or "What was my cache offload by CP code yesterday?" and the assistant calls these tools:

• traffic by hostname or CP code

• HTTP response-class breakdown (2xx–5xx)

• edge/origin offload

• flexible raw queries

• traffic forecasts

• Excel export

The server runs on your machine and talks only to the Akamai account your credentials belong to. Your credentials never leave your machine.

Prerequisites

• Python 3.10 or newer (3.12+ recommended).

• An Akamai API client with read access to the Reporting API, and access to the groups/CP codes you want to report on. Create one in Akamai Control Center under Identity and Access Management → API clients.

• An MCP client, such as Claude Code or Claude Desktop.

Related MCP server: Akamai Traffic MCP

Setup

1. Clone and install

macOS / Linux:

git clone https://github.com/gamittal-ak/akamai-traffic-mcp.git
cd akamai-traffic-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Windows (PowerShell):

git clone https://github.com/gamittal-ak/akamai-traffic-mcp.git
cd akamai-traffic-mcp
py -3 -m venv .venv
.venv\Scripts\Activate.ps1
pip install -r requirements.txt

2. Add your credentials to ~/.edgerc

Put the values from your API client's credential into ~/.edgerc (on Windows: C:\Users\<you>\.edgerc). The section name is [default] unless you choose otherwise:

[default]
client_secret = xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
host = akab-xxxxxxxxxxxxxxxx-xxxxxxxxxxxxxxxx.luna.akamaiapis.net
access_token = akab-xxxxxxxxxxxxxxxx-xxxxxxxxxxxxxxxx
client_token = akab-xxxxxxxxxxxxxxxx-xxxxxxxxxxxxxxxx

• host is the bare hostname, without https://.

• To use a different file or section, set EDGERC_PATH / EDGERC_SECTION (see Configuration).

3. Check your credential

python scripts/smoke_test.py

It checks the .edgerc section, that the Akamai API host is reachable, and one small Reporting API call. It ends with READY, or NOT READY plus the first thing to fix. Credential values are never printed.

[PASS] .edgerc: section [default] has all required keys
[PASS] client init: signed client built from .edgerc
[PASS] reachability: API host reachable (HTTP 400)
[PASS] reporting: Reporting API works — 5 row(s) returned
READY

(An HTTP 400 on the reachability line is normal: that check only confirms the host answers.)

Use --section or --edgerc to test a different section or file.

4. Connect your MCP client

You don't start the server yourself. Your MCP client launches server.py over stdio whenever it needs it. The client needs two absolute paths: the venv's Python and server.py. Print them from the project folder:

macOS / Linux:

echo "$PWD/.venv/bin/python"     # e.g. /Users/you/akamai-traffic-mcp/.venv/bin/python
echo "$PWD/server.py"            # e.g. /Users/you/akamai-traffic-mcp/server.py

Windows (PowerShell):

(Resolve-Path .venv\Scripts\python.exe).Path   # e.g. C:\Users\you\akamai-traffic-mcp\.venv\Scripts\python.exe
(Resolve-Path server.py).Path                  # e.g. C:\Users\you\akamai-traffic-mcp\server.py

Claude Code

macOS / Linux:

claude mcp add --scope user akamai-traffic -- /Users/you/akamai-traffic-mcp/.venv/bin/python /Users/you/akamai-traffic-mcp/server.py

Windows (PowerShell):

claude mcp add --scope user akamai-traffic -- C:\Users\you\akamai-traffic-mcp\.venv\Scripts\python.exe C:\Users\you\akamai-traffic-mcp\server.py

• --scope user makes the server available in every project. Without it, the default local scope applies to the current project only.

• For a non-default credential file or section, add -e options after the name and before --, e.g. claude mcp add --scope user akamai-traffic -e EDGERC_SECTION=reporting -- ....

• Start claude and run /mcp to confirm akamai-traffic is connected.

Claude Desktop

Edit the config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

macOS / Linux:

{
  "mcpServers": {
    "akamai-traffic": {
      "command": "/Users/you/akamai-traffic-mcp/.venv/bin/python",
      "args": ["/Users/you/akamai-traffic-mcp/server.py"]
    }
  }
}

Windows (backslashes doubled, as JSON requires):

{
  "mcpServers": {
    "akamai-traffic": {
      "command": "C:\\Users\\you\\akamai-traffic-mcp\\.venv\\Scripts\\python.exe",
      "args": ["C:\\Users\\you\\akamai-traffic-mcp\\server.py"]
    }
  }
}

• For a non-default credential file or section, add an env block next to args, e.g. "env": {"EDGERC_PATH": "/Users/you/creds/.edgerc", "EDGERC_SECTION": "reporting"}.

• Use absolute paths there too.

• Fully quit and reopen Claude Desktop. The Akamai traffic tools appear in the tools menu.

Other MCP clients: configure a stdio server with the venv's Python as the command and the absolute path to server.py as its argument.

Now ask, for example: "Show traffic by hostname for www.example.com on 2026-01-15."

Excel exports

export_traffic_report saves reports to ~/akamai-traffic-reports/ (created automatically) and returns the full path of the file. Set EXPORT_DIR to use another folder.

Run as an HTTP server (optional)

Use this only if your client can't launch stdio servers, or you want one long-running server:

python server.py --transport http            # http://127.0.0.1:8000/mcp
python server.py --transport http --port 9000

• It uses streamable HTTP at http://127.0.0.1:8000/mcp. Keep the terminal open.

• Connect Claude Code with claude mcp add --transport http akamai-traffic http://127.0.0.1:8000/mcp.

• --host / --port override MCP_HOST / MCP_PORT.

Security: the HTTP server has no authentication. Keep it on 127.0.0.1. With --host 0.0.0.0 or a network address, anyone who can reach the port can query your Akamai traffic data. On 127.0.0.1 it also rejects requests whose Host or Origin header isn't localhost (HTTP 421 / 403), which blocks browser-based attacks.

Configuration

All settings are optional:

• Set them as environment variables: in your MCP client's env block, or with claude mcp add -e.

• Or put them in a .env file in the project folder (see .env.example). It's found no matter which folder the client starts the server from.

Relative paths are resolved against your home folder.

Tool reference

About every tool:

• All times are ISO-8601 in UTC, e.g. 2026-01-15T00:00:00Z.

• When omitted, start defaults to 15 days ago and end to now.

• cpcode filters take integers (e.g. [123456]).

• hostname filters take exact hostnames (e.g. ["www.example.com"]).

• In tool responses, byte metrics (edgeBytesSum, originBytesSum, midgressBytesSum) are converted to GB.

get_raw_traffic

• Dimensions: cpcode, hostname, responseCode, responseClass, time5minutes, time1hour, time1day, httpMethod, deliveryType.

• Metrics: edgeBytesSum, edgeHitsSum, originBytesSum, originHitsSum, midgressBytesSum, midgressHitsSum, offloadedBytesPercentage, offloadedHitsPercentage.

predict_traffic

• metric is one of edgeBytesSum, edgeHitsSum, originBytesSum, originHitsSum.

• granularity is time1day, time1hour or time5minutes.

• method is linear (least-squares trend) or ema (exponential moving average; alpha sets its smoothing).

• It needs at least 3 data points in the window.

export_traffic_report

• filename is a relative path inside EXPORT_DIR (e.g. report.xlsx or weekly/report.xlsx), and .xlsx is added if missing.

• Absolute paths and paths that escape the folder (e.g. ../x.xlsx) are rejected.

• In the Excel file, byte values are shown human-readable (KB/MB/GB/TB).

Troubleshooting

HTTP 401 (authentication failed)

• The .edgerc values don't match the API client, or your system clock is off.

• Re-copy host, client_token, client_secret and access_token exactly, make sure host has no https://, and sync your clock.

HTTP 403 (access denied)

• The API client lacks Reporting API read access, or access to the groups/CP codes you asked about.

• Grant them in Akamai Control Center under Identity and Access Management → API clients, then run the smoke test again.

Empty results

• Times are UTC, so a local-time day may span two UTC days. Widen the range.

• Very recent traffic can take a while to appear in reports.

• Hostname filters must match the hostname exactly as Akamai reports it.

• Traffic for CP codes outside the API client's groups isn't returned.

Timeouts

• Reporting calls time out after 60 seconds.

• Long ranges at fine granularity (e.g. time5minutes over weeks) are slow. Narrow the time range or use time1hour/time1day.

The client can't start the server (tools don't appear, or the server shows as failed)

• Both paths in the client config must be absolute. Use the venv's Python (.venv/bin/python or .venv\Scripts\python.exe), not the system python, or the dependencies won't be found.

• Make sure the venv exists and pip install -r requirements.txt succeeded.

• Run the exact command yourself:

  • macOS / Linux: /Users/you/akamai-traffic-mcp/.venv/bin/python /Users/you/akamai-traffic-mcp/server.py

  • Windows: the same with the .venv\Scripts\python.exe path

  • It should log Starting AkamaiTrafficMCP (transport: stdio) and wait. Press Ctrl+C to stop it.

  • Any error it prints is the one your client hit.

• After editing the Claude Desktop config, fully quit and reopen it.

Where are the server logs?

• The server logs to stderr, never stdout: stdout carries the MCP protocol.

• Claude Code: run /mcp to see the server status, or start claude --debug for details.

• Claude Desktop: open the MCP log files from Settings → Developer, or look in ~/Library/Logs/Claude/ (macOS) or %APPDATA%\Claude\logs\ (Windows).

• For more detail, set LOG_LEVEL=DEBUG. Credentials are still never logged.

.edgerc not found / Section [...] not found

• Check the file location and section name, or set EDGERC_PATH / EDGERC_SECTION in the client's env.

• The server resolves paths without depending on the folder the client starts it from.

HTTP mode: the client can't connect

• python server.py --transport http must be running, and the URL must be exactly http://127.0.0.1:8000/mcp.

• HTTP 421 / 403 means the request's Host or Origin isn't localhost. That's the expected browser-attack protection.

Project layout

server.py              MCP server and tool definitions
config.py              Settings (environment variables / .env)
akamai_api/client.py   EdgeGrid-signed HTTP client, error handling, timeouts
akamai_api/reports.py  Reporting API request bodies
forecast.py            Forecasting (numpy)
export.py              Excel report writer (openpyxl)
scripts/smoke_test.py  First-run credential check

Disclaimer

This is an independent, community project. It is not an official Akamai product and is not supported by Akamai Technologies. Akamai is a trademark of Akamai Technologies, Inc.

License

MIT — see LICENSE.