# Akamai Traffic MCP

An [MCP](https://modelcontextprotocol.io) 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.

---

## Setup

### 1. Clone and install

macOS / Linux:

```bash
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):

```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:

```ini
[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](#configuration)).

### 3. Check your credential

```bash
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:

```bash
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):

```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:

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

Windows (PowerShell):

```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:

```json
{
  "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):

```json
{
  "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:

```bash
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.

| Variable | Default | Purpose |
|---|---|---|
| `EDGERC_PATH` | `~/.edgerc` | Credential file |
| `EDGERC_SECTION` | `default` | Section inside the credential file |
| `EXPORT_DIR` | `~/akamai-traffic-reports` | Where Excel reports are written |
| `LOG_LEVEL` | `INFO` | Log level (logs go to stderr) |
| `MCP_TRANSPORT` | `stdio` | `stdio` or `http`; the `--transport` flag wins |
| `MCP_HOST` | `127.0.0.1` | HTTP mode only: interface to listen on |
| `MCP_PORT` | `8000` | HTTP mode only: port to listen on |

---

## 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**.

| Tool | Parameters | Returns |
|---|---|---|
| `get_traffic_by_hostname` | `start`, `end`, `cpcode`, `hostname` | Per hostname: `edgeBytesSum`, `edgeHitsSum`, `originBytesSum`, `originHitsSum`, `midgressBytesSum` |
| `get_traffic_by_cpcode` | `start`, `end`, `cpcode` | Per CP code: `edgeBytesSum`, `originBytesSum`, `midgressBytesSum`, `offloadedBytesPercentage` |
| `get_http_status_breakdown` | `start`, `end`, `cpcode` | Per response class (2xx–5xx): `edgeHitsSum`, `originHitsSum` |
| `get_edge_origin_offload` | `start`, `end`, `cpcode` | Per CP code: `offloadedBytesPercentage`, `offloadedHitsPercentage`, `edgeBytesSum`, `originBytesSum` |
| `get_raw_traffic` | `dimensions`, `metrics` (required); `start`, `end`, `cpcode`, `limit` (default 50000) | Any combination of the dimensions and metrics below |
| `predict_traffic` | `metric` (required); `start`, `end`, `forecast_periods` (7), `granularity` (`time1day`), `method` (`linear`), `alpha` (0.3), `cpcode`, `hostname` | Trend, summary, historical and forecast points |
| `export_traffic_report` | `start`, `end`, `cpcode`, `hostname`, `filename` (`akamai_traffic_report.xlsx`) | Path of a multi-sheet Excel file (hostname, CP code, HTTP status, offload) written to `EXPORT_DIR` |

**`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](LICENSE).