Metadata-Version: 2.4
Name: mcp-trafficpeak
Version: 0.3.5a1
Summary: An MCP server for TrafficPeak.
Project-URL: Home, https://www.akamai.com/products/trafficpeak
Project-URL: Source, https://github.com/hydrolix/mcp-trafficpeak
License-Expression: Apache-2.0
License-File: LICENSE
Requires-Python: >=3.13
Requires-Dist: clickhouse-connect<0.16,>=0.15
Requires-Dist: fastmcp<3.4,>=3.3.0
Requires-Dist: prometheus-client<1.0,>=0.21
Requires-Dist: pyjwt<3,>=2.13.0
Requires-Dist: python-dotenv<1.3,>=1.1
Requires-Dist: sqlglot<27.0,>=26.0
Requires-Dist: truststore>=0.10
Requires-Dist: uvicorn[standard]<1.0,>=0.34
Provides-Extra: dev
Requires-Dist: httpx<0.29,>=0.27; extra == 'dev'
Requires-Dist: kubernetes<32,>=30; extra == 'dev'
Requires-Dist: mcp-clickhouse==0.1.13; extra == 'dev'
Requires-Dist: pre-commit; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-asyncio; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Description-Content-Type: text/markdown

# TrafficPeak MCP Server

<!-- mcp-name: io.github.hydrolix/mcp-trafficpeak -->

[![PyPI - Version](https://img.shields.io/pypi/v/mcp-trafficpeak)](https://pypi.org/project/mcp-trafficpeak)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_mcp--trafficpeak-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect/mcp/install?name=mcp-trafficpeak&config=%7B%22type%22%3A%22stdio%22%2C%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22--python%22%2C%223.13%22%2C%22--refresh-package%22%2C%22mcp-trafficpeak%22%2C%22mcp-trafficpeak%22%5D%2C%22env%22%3A%7B%22TRAFFICPEAK_URL%22%3A%22%24%7Binput%3Atrafficpeak_url%7D%22%2C%22TRAFFICPEAK_USER%22%3A%22%24%7Binput%3Atrafficpeak_user%7D%22%2C%22TRAFFICPEAK_PASSWORD%22%3A%22%24%7Binput%3Atrafficpeak_password%7D%22%7D%7D&inputs=%5B%7B%22id%22%3A%22trafficpeak_url%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22TrafficPeak%20URL%20%28e.g.%20https%3A%2F%2Fmycluster.trafficpeak.live%29%22%7D%2C%7B%22id%22%3A%22trafficpeak_user%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22TrafficPeak%20username%22%7D%2C%7B%22id%22%3A%22trafficpeak_password%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22TrafficPeak%20password%22%2C%22password%22%3Atrue%7D%5D)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install_mcp--trafficpeak-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=mcp-trafficpeak&quality=insiders&config=%7B%22type%22%3A%22stdio%22%2C%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22--python%22%2C%223.13%22%2C%22--refresh-package%22%2C%22mcp-trafficpeak%22%2C%22mcp-trafficpeak%22%5D%2C%22env%22%3A%7B%22TRAFFICPEAK_URL%22%3A%22%24%7Binput%3Atrafficpeak_url%7D%22%2C%22TRAFFICPEAK_USER%22%3A%22%24%7Binput%3Atrafficpeak_user%7D%22%2C%22TRAFFICPEAK_PASSWORD%22%3A%22%24%7Binput%3Atrafficpeak_password%7D%22%7D%7D&inputs=%5B%7B%22id%22%3A%22trafficpeak_url%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22TrafficPeak%20URL%20%28e.g.%20https%3A%2F%2Fmycluster.trafficpeak.live%29%22%7D%2C%7B%22id%22%3A%22trafficpeak_user%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22TrafficPeak%20username%22%7D%2C%7B%22id%22%3A%22trafficpeak_password%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22TrafficPeak%20password%22%2C%22password%22%3Atrue%7D%5D)

An MCP server for TrafficPeak.

## Quickstart

Get up and running in a few minutes. This section covers Claude Desktop and Claude Code.

### Step 1 — Prerequisites

Before you begin, make sure you have:

- **TrafficPeak credentials** — your cluster hostname plus either a username/password or a service account token. If you don't have these, ask your TrafficPeak administrator.
- **Claude Desktop** — download from [claude.ai/download](https://claude.ai/download).

### Step 2 — Install the MCP server

Choose the method that matches your setup:

**Option A: Using uv (recommended)**

[uv](https://docs.astral.sh/uv/) manages Python automatically and downloads mcp-trafficpeak on demand, so no separate install step is needed. If you don't have uv, install it:

macOS / Linux:
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

Windows (PowerShell):
```powershell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```

**Option B: Using pip**

Requires Python 3.13+. If you need to install Python, download it from [python.org](https://www.python.org/downloads/).

```bash
pip install mcp-trafficpeak
```

### Step 3 — Configure Claude Desktop

1. Open the Claude Desktop configuration file:
   - **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
   - **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
   - **Linux:** `~/.config/Claude/claude_desktop_config.json`

2. Add the following entry to the `"mcpServers"` object (create the file with this content if it doesn't exist yet):

```json
{
  "mcpServers": {
    "mcp-trafficpeak": {
      "command": "uvx",
      "args": [
        "--python",
        "3.13",
        "--refresh-package",
        "mcp-trafficpeak",
        "mcp-trafficpeak"
      ],
      "env": {
        "TRAFFICPEAK_URL": "https://<your-trafficpeak-hostname>",
        "TRAFFICPEAK_USER": "<your-username>",
        "TRAFFICPEAK_PASSWORD": "<your-password>"
      }
    }
  }
}
```

Replace `<your-trafficpeak-hostname>`, `<your-username>`, and `<your-password>` with your actual credentials.

> [!NOTE]
> If you used Option B (pip), use `"command": "mcp-trafficpeak"` with no `"args"` field instead.

> [!TIP]
> If the file already has other entries, add the `"mcp-trafficpeak"` block inside the existing `"mcpServers"` object rather than replacing the whole file.

> [!NOTE]
> If you authenticate with a service account token instead of username/password, see [Authentication](#authentication).

<details>
<summary><strong>Command not found?</strong></summary>

Claude Desktop launches without your shell's PATH, so it may not locate the binary even if it is installed. Find the full path and use it as the `"command"` value in the config.

**Option A (uv):** find `uvx`:

- **macOS / Linux:** `which uvx`
- **Windows:** `where.exe uvx`

**Option B (pip):** find `mcp-trafficpeak`:

- **macOS / Linux:** `which mcp-trafficpeak`
- **Windows:** `where.exe mcp-trafficpeak`

If `which`/`where.exe` returns nothing, the binary isn't on your PATH. The cleanest fix is to switch to Option A (uv), which manages the Python environment and PATH for you.

</details>

### Step 4 — Restart Claude Desktop

Restart the app to apply the configuration.

> **macOS / Windows users:** Make sure to fully quit Claude before restarting. On macOS, press Cmd+Q or right-click the Dock icon and choose Quit. On Windows, use the system tray icon.

### Step 5 — Verify it's working

1. Open a new conversation in Claude Desktop. Look for a tools/hammer icon near the text input — this confirms the MCP server connected successfully.

2. Try this prompt to confirm everything is working:

   > Using your TrafficPeak MCP tools, list the available databases.

Claude should call the `list_databases` tool and return a list of databases from your cluster.

---

### Using Claude Code instead?

If you prefer the command line, make sure uv is installed (Option A from [Step 2](#step-2--install-the-mcp-server)), then run:

```bash
claude mcp add --transport stdio trafficpeak \
  --env TRAFFICPEAK_URL=https://<your-trafficpeak-hostname> \
  --env TRAFFICPEAK_USER=<your-username> \
  --env TRAFFICPEAK_PASSWORD=<your-password> \
  --env TRAFFICPEAK_MCP_SERVER_TRANSPORT=stdio \
  -- uvx --python 3.13 --refresh-package mcp-trafficpeak mcp-trafficpeak
```

Then open Claude Code and test with the same prompt:

> Using your TrafficPeak MCP tools, list the available databases.

### Using VS Code instead?

Click the **Install in VS Code** badge at the top of this README for a one-click install. If you prefer the UI flow, open the Command Palette (**Cmd+Shift+P** / **Ctrl+Shift+P**), run **MCP: Add Server**, choose **Command (stdio)**, and reuse the `uvx ...` command and `env` block from [Step 3](#step-3--configure-claude-desktop).

## Tools

* `run_select_query`
  * Execute SQL queries on your TrafficPeak cluster.
  * Input: `sql` (string): The SQL query to execute.

* `list_databases`
  * List all databases on your TrafficPeak cluster.

* `list_tables`
  * List all tables in a database.
  * Input: `database` (string): The name of the database.

* `get_table_info`
  * Get table metadata such as schema
  * Input: `database` (string): The name of the database.
  * Input: `table` (string): The name of the table.

## Effective Usage

Due to the wide variety in LLM architectures, not all models will proactively use the tools above, and few will use them effectively without guidance, even with the carefully-constructed tool descriptions provided to the model. To get the best results out of your model while using the TrafficPeak MCP server, we recommend the following:

* Refer to your TrafficPeak database by name and request tool usage in your prompts (e.g., "Using MCP tools to access my TrafficPeak database, please ...")
  - This encourages the model to use the MCP tools available and minimizes hallucinations.
* Include time ranges in your prompts (e.g., "Between December 5 2023 and January 18 2024, ...") and specifically request that the output be ordered by timestamp.
  - This prompts the model to write more efficient queries that take advantage of [primary key optimizations](https://trafficpeak.io/blog/optimizing-latest-n-row-queries/)

### Health Check Endpoint

When running with HTTP or SSE transport, a health check endpoint is available at `/health`. This endpoint:
- Returns `200 OK` with the TrafficPeak query-head's Clickhouse version if the server is healthy and can connect to TrafficPeak
- Returns `503 Service Unavailable` if the server cannot connect to the TrafficPeak query-head

Example:
```bash
curl http://localhost:8000/health
# Response: OK - Connected to TrafficPeak compatible with ClickHouse 24.3.1
```

## Configuration

The TrafficPeak MCP server is configured using a standard MCP server entry. Consult your client's documentation for specific instructions on where to find or declare MCP servers. An example setup using Claude Desktop is documented below.

The recommended way to launch the TrafficPeak MCP server is via the [`uv` project manager](https://github.com/astral-sh/uv), which will manage installing all other dependencies in an isolated environment.

### Authentication

The server supports multiple authentication methods with the following precedence (highest to lowest):

1. **Per-request Bearer token**: Service account token provided via `Authorization: Bearer <token>` header
2. **Per-request GET parameter**: Service account token provided via `?token=<token>` query parameter
3. **Environment-based credentials**: Credentials configured via environment variables
   - Service account token (`TRAFFICPEAK_TOKEN`), or
   - Username and password (`TRAFFICPEAK_USER` and `TRAFFICPEAK_PASSWORD`)

When multiple authentication methods are configured, the server will use the first available method in the precedence order above. Per-request authentication is only available when using HTTP or SSE transport modes.

**Note: Using a service account token with a readonly role is recommended.**

MCP Server definition using username and password (JSON):

```json
{
  "command": "uvx",
  "args": [
    "--python",
    "3.13",
    "--refresh-package",
    "mcp-trafficpeak",
    "mcp-trafficpeak"
  ],
  "env": {
    "TRAFFICPEAK_URL": "https://<trafficpeak-host>",
    "TRAFFICPEAK_USER": "<trafficpeak-user>",
    "TRAFFICPEAK_PASSWORD": "<trafficpeak-password>"
  }
}
```

MCP Server definition using service account token (JSON):

```json
{
  "command": "uvx",
  "args": [
    "--python",
    "3.13",
    "--refresh-package",
    "mcp-trafficpeak",
    "mcp-trafficpeak"
  ],
  "env": {
    "TRAFFICPEAK_URL": "https://<trafficpeak-host>",
    "TRAFFICPEAK_TOKEN": "<trafficpeak-service-account-token>"
  }
}
```

MCP Server definition using username and password (YAML):

```yaml
command: uvx
args:
- --python
- "3.13"
- --refresh-package
- mcp-trafficpeak
- mcp-trafficpeak
env:
  TRAFFICPEAK_URL: https://<trafficpeak-host>
  TRAFFICPEAK_USER: <trafficpeak-user>
  TRAFFICPEAK_PASSWORD: <trafficpeak-password>
```

MCP Server definition using service account token (YAML):

```yaml
command: uvx
args:
- --python
- "3.13"
- --refresh-package
- mcp-trafficpeak
- mcp-trafficpeak
env:
  TRAFFICPEAK_URL: https://<trafficpeak-host>
  TRAFFICPEAK_TOKEN: <trafficpeak-service-account-token>
```

### Configuration Example (Claude Desktop)

1. Open the Claude Desktop configuration file located at:
   - On macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
   - On Windows: `%APPDATA%/Claude/claude_desktop_config.json`

2. Add a `mcp-trafficpeak` server entry to the `mcpServers` config block to use username and password:

```json
{
  "mcpServers": {
    "mcp-trafficpeak": {
      "command": "uvx",
      "args": [
        "--python",
        "3.13",
        "--refresh-package",
        "mcp-trafficpeak",
        "mcp-trafficpeak"
      ],
      "env": {
        "TRAFFICPEAK_URL": "https://<trafficpeak-host>",
        "TRAFFICPEAK_USER": "<trafficpeak-user>",
        "TRAFFICPEAK_PASSWORD": "<trafficpeak-password>"
      }
    }
  }
}
```

To leverage service account use the following config block:

```json
{
  "mcpServers": {
    "mcp-trafficpeak": {
      "command": "uvx",
      "args": [
        "--python",
        "3.13",
        "--refresh-package",
        "mcp-trafficpeak",
        "mcp-trafficpeak"
      ],
      "env": {
        "TRAFFICPEAK_URL": "https://<trafficpeak-host>",
        "TRAFFICPEAK_TOKEN": "<trafficpeak-service-account-token>"
      }
    }
  }
}
```

3. Update the environment variable definitions to point to your TrafficPeak cluster.

4. (Recommended) Locate the command entry for `uvx` and replace it with the absolute path to the `uvx` executable. This ensures that the correct version of `uvx` is used when starting the server. You can find this path using `which uvx` or `where.exe uvx`.

5. Restart Claude Desktop to apply the changes. If you are using Windows, ensure Claude is stopped completely by closing the client using the system tray icon.

### Configuration Example (Claude Code)

To configure the TrafficPeak MCP server for Claude Code, run the following command:

```bash
claude mcp add --transport stdio trafficpeak \
  --env TRAFFICPEAK_USER=<trafficpeak-user> \
  --env TRAFFICPEAK_PASSWORD=<trafficpeak-password> \
  --env TRAFFICPEAK_URL=https://<trafficpeak-host> \
  --env TRAFFICPEAK_MCP_SERVER_TRANSPORT=stdio \
  -- uvx --python 3.13 --refresh-package mcp-trafficpeak mcp-trafficpeak
```

### Environment Variables

The following variables are used to configure the TrafficPeak connection. These variables may be provided via the MCP config block (as shown above), a `.env` file, or traditional environment variables.

#### Required Variables

You MUST set one of the following to identify the cluster:

* `TRAFFICPEAK_URL` *(recommended)*: The canonical public URL of your TrafficPeak cluster, e.g. `https://mycluster.trafficpeak.live`. For typical out-of-cluster deployments this single variable is sufficient — it supplies the host, port (scheme-default 443/80), and TLS settings for both the HTTP query endpoint and the REST `/version` probe.
* `TRAFFICPEAK_HOST` *(deprecated)*: The hostname of your TrafficPeak server. Still honored for backwards compatibility but should be replaced by `TRAFFICPEAK_URL`.

When `TRAFFICPEAK_MCP_SERVER_TRANSPORT` is `http` or `sse`, `TRAFFICPEAK_URL` *specifically* is required (a forthcoming OAuth metadata endpoint would advertise it). `TRAFFICPEAK_HOST` alone is not sufficient for these transports.

#### Authentication Variables
At least one authentication method must be configured when using the stdio transport:

* `TRAFFICPEAK_TOKEN`: Service account token for environment-based authentication
* `TRAFFICPEAK_USER` and `TRAFFICPEAK_PASSWORD`: Username and password for environment-based authentication (both must be provided together)

In summary:
- For stdio, you MUST use TRAFFICPEAK_TOKEN or TRAFFICPEAK_USER+TRAFFICPEAK_PASS (environmental credentials)
- For http/sse, you MAY use TRAFFICPEAK_TOKEN or TRAFFICPEAK_USER+TRAFFICPEAK_PASS (environmental credentials), but you may instead use per-request credentials.

If no credentials are provided via the environment or the request, the request will fail.

#### Using Per-Request Authentication with HTTP Transport

When using HTTP or SSE transport, you can omit environment-based credentials and instead provide authentication per-request. This is useful for multi-user scenarios or with clients that don't support running MCP servers locally.

Example `mcpServers` configuration connecting to a remote HTTP server with per-request authentication:

```json
{
  "mcpServers": {
    "mcp-trafficpeak-remote": {
      "url": "https://my-trafficpeak-mcp.example.com/mcp?token=<service-account-token>"
    }
  }
}
```

Example minimal `.env` configuration for running your own HTTP server without environment credentials:

```env
TRAFFICPEAK_URL=https://my-cluster.trafficpeak.net
TRAFFICPEAK_MCP_SERVER_TRANSPORT=http
```

Though not part of the MCP specification, many MCP clients allow adding headers to MCP-issued requests. When this is possible, we recommend configuring the MCP client to pass a service account token via the `Authorization: Bearer <sa-token-here>` header instead of as a query parameter for greater security.

Note: The bind host and port settings are only used when transport is set to "http" or "sse".

#### Optional Variables

See **[docs/CONFIG.md](docs/CONFIG.md)** for endpoint overrides, deprecated variable aliases, and the full set of optional tuning variables (timeouts, query SETTINGS overrides, result truncation, HTTP/SSE worker tuning, proxy, metrics, and escape hatches).

## Maintainers

Tasks that need operational privileges — running the end-to-end suite against a
live TrafficPeak cluster, and cutting a release — are documented separately in
[`MAINTAINERS.md`](MAINTAINERS.md).
