How do I install Tideways?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does Tideways need an API key?

The publisher lists these environment variables: TIDEWAYS_TOKEN, TIDEWAYS_ORG, TIDEWAYS_PROJECT, TIDEWAYS_ENV, TIDEWAYS_SERVICE.

What transport does Tideways use?

Tideways runs locally over stdio.

When was Tideways last checked?

Last checked 2026-11-09. Read-only access to Tideways PHP performance monitoring: performance, issues, traces, history.

Tideways MCP server

Power your agent

Add this server

The publisher's own command. Not a PlugMCP endpoint.

Add to Cursor Add to VS Code Run on PlugMCP

Host a copy with our keys and logs.

Local command

npx -y [email protected]

Credentials from the publisher

TIDEWAYS_TOKEN — Tideways API token (Organization settings → API Access; scopes metrics, traces, errors).
TIDEWAYS_ORG — Tideways organization (optional; derived from the token).
TIDEWAYS_PROJECT — Default project, "project" or "organization/project" (optional if the token reaches one project).
TIDEWAYS_ENV — Default environment, e.g. production (optional).
TIDEWAYS_SERVICE — Default service, e.g. web (optional; API default is the project's default service).

Claude Code has no install link for a local command. Copy the command below and run it in a terminal.

shClaude Code

1TIDEWAYS_TOKEN=<secret> TIDEWAYS_ORG=<value> TIDEWAYS_PROJECT=<value> TIDEWAYS_ENV=<value> TIDEWAYS_SERVICE=<value> claude mcp add io.github.abuhamza-tideways-mcp-server -- npx -y tideways-mcp-server@2.1.1

Run in a terminal.

jsonClaude Desktop

1{2  "mcpServers": {3    "io.github.abuhamza-tideways-mcp-server": {4      "command": "npx",5      "args": [6        "-y",7        "[email protected]"8      ],9      "env": {10        "TIDEWAYS_TOKEN": "<secret>",11        "TIDEWAYS_ORG": "<value>",12        "TIDEWAYS_PROJECT": "<value>",13        "TIDEWAYS_ENV": "<value>",14        "TIDEWAYS_SERVICE": "<value>"15      }16    }17  }18}

claude_desktop_config.json

Local · npmPublisher installStep-by-step: add this in Claude

Remote URL or a command on your machine? How the two installs differ

Run on PlugMCP

Host a copy with our keys and logs.

A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.

Launch

Server facts

Local

Transport

Tools

No tool list yet. Remote servers get one after the first health check.

FAQ

Questions

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 opencode.json in the project, or to ~/.config/opencode/opencode.json for all projects. {env:TIDEWAYS_TOKEN} reads the token from your shell's environment.

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "tideways": {
      "type": "local",
      "command": ["npx", "-y", "tideways-mcp-server"],
      "environment": { "TIDEWAYS_TOKEN": "{env:TIDEWAYS_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

Tool	Answers
`tideways_list_projects`	Which projects and scopes does my token have, and how much of the hourly rate limit is left?
`tideways_list_services`	Which services does a project have, and which of them serve "voucher"?
`tideways_get_performance`	How is the app doing in any window of up to 24 h within the last ~30 days? Totals, layers, top transactions
`tideways_get_transaction`	When did one transaction get slow, and in which layer? Per-minute timeline and response-time histogram
`tideways_get_performance_summary`	Requests, errors and p95 in 15-minute buckets over up to 30 days
`tideways_list_issues`	Which errors, slow SQL queries, deprecations, warnings or notices are open, resolved or ignored, in any service or transaction?
`tideways_get_issue`	Where in the code does an issue fail, which transactions does it hit, and when did it start or stop?
`tideways_search_traces`	Which individual requests were slow, in any transaction, and where did the time go?
`tideways_get_history`	Day, week or month report for a past date
`tideways_get_observations`	Configuration problems and code bottlenecks Tideways detected (e.g. N+1 queries)

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.

Variable	Default	Meaning
`TIDEWAYS_TOKEN`	required	API token
`TIDEWAYS_PROJECT`	the token's only project	Default project; with several projects and no default, pass `project` per call
`TIDEWAYS_ORG`	from the token's projects	Organization, to match a plain project name
`TIDEWAYS_ENV`	API default	Default environment
`TIDEWAYS_SERVICE`	the project's default service	Default service
`TIDEWAYS_BASE_URL`	`https://app.tideways.io/apps/api`	API base URL, https only
`TIDEWAYS_REQUEST_TIMEOUT`	`30000`	Request timeout in ms, a positive integer up to `600000`
`LOG_LEVEL`	`info`	`debug`, `info`, `warn` or `error`, case-insensitive; logs go to stderr

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 the issues of all services, and its search costs one request per service.
tideways_search_traces returns 30 traces per call, or up to 100 with limit.
Limits of the Tideways API: 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 check                      # the gate: typecheck, lint, format, tests, commit messages
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

Add this server

Host a copy with our keys and logs.

Server facts

Tools

Questions

How do I install Tideways?

Does Tideways need an API key?

What transport does Tideways use?

When was Tideways last checked?

Documentation

Tideways MCP Server

Install

Tools

Configuration

Good to know

Security

Development

License