Tideways MCP Server

Tideways MCP Server

An unofficial, community-maintained server, not affiliated with or supported by Tideways. For Tideways' own tooling, see the official Tideways CLI.

A read-only Model Context Protocol server for Tideways. It lets an AI assistant answer questions such as "why was checkout slow yesterday?" from your performance data, issues and traces. It only calls GET endpoints of the Tideways REST API.

Install

You need a Tideways API token with the scopes metrics, traces and errors (Organization settings → API Access), and Node.js 22+ or Docker. Coming from 1.x? See UPGRADING.md.

claude mcp add tideways -e TIDEWAYS_TOKEN=your-token -- npx -y tideways-mcp-server

Add -s user to use it in every project.

Open the .mcpb bundle from the latest release. It asks for the token and keeps it in the OS keychain.

codex mcp add tideways --env TIDEWAYS_TOKEN=your-token -- npx -y tideways-mcp-server

The Codex CLI, IDE extension and app share this entry in ~/.codex/config.toml.

Add to the client's MCP configuration (Cursor: ~/.cursor/mcp.json; Gemini CLI: ~/.gemini/settings.json; either also per project):

{
  "mcpServers": {
    "tideways": {
      "command": "npx",
      "args": ["-y", "tideways-mcp-server"],
      "env": { "TIDEWAYS_TOKEN": "your-token" }
    }
  }
}

Add to .vscode/mcp.json, or run MCP: Open User Configuration for all workspaces. VS Code asks for the token on first start and stores it.

{
  "inputs": [
    { "type": "promptString", "id": "tideways-token", "description": "Tideways API token", "password": true }
  ],
  "servers": {
    "tideways": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "tideways-mcp-server"],
      "env": { "TIDEWAYS_TOKEN": "${input:tideways-token}" }
    }
  }
}

In any setup above, replace npx -y tideways-mcp-server with docker run -i --rm -e TIDEWAYS_TOKEN ghcr.io/abuhamza/tideways-mcp-server (pin a version with :2.0.0). For example:

claude mcp add tideways -e TIDEWAYS_TOKEN=your-token -- docker run -i --rm -e TIDEWAYS_TOKEN ghcr.io/abuhamza/tideways-mcp-server

"command": "docker",
"args": ["run", "-i", "--rm", "-e", "TIDEWAYS_TOKEN", "ghcr.io/abuhamza/tideways-mcp-server"],
"env": { "TIDEWAYS_TOKEN": "your-token" }

Tools

All tools except tideways_list_projects take an optional project (name or organization/name).

Configuration

Environment variables; empty values count as unset. The server does not load .env files.

Good to know

• All times are UTC, YYYY-MM-DD HH:mm. The API rate limit is per Tideways organization and clock hour; its size depends on the plan, and all tokens and projects of the organization share it.
• Tools read the project's default service unless you name one; tideways_list_issues reads all services. The API cannot list services; tideways_list_services finds them through open issues, and its search costs one request per service.
• Limits of the Tideways API: at most 30 traces per search, history for production and the default service only, issues 10 per page, and no trace filter by bottleneck (an N+1 observation's link opens the affected traces in Tideways).

Security

The token is read from the environment and never logged, and trace URLs are returned without query strings. Report vulnerabilities privately as described in SECURITY.md.

Development

npm ci
npm run typecheck && npm run lint && npm run format:check && npm test   # the gate
npm run build && npm run inspect                                        # try the tools in the MCP Inspector

Architecture, invariants and how to add a tool: CLAUDE.md. Commits follow Conventional Commits.

License

MIT