Tideways

io.github.abuhamzav2.0.0Updated Oct 3, 2026

Read-only access to Tideways PHP performance monitoring: performance, issues, traces, history.

VerifiedSTDIODesktop onlySecurity & MonitoringData & Analytics

Overview

AI-generated overview

Read-only access to Tideways PHP performance monitoring, letting an assistant query performance, issues, traces and history.

What it does
Wraps the Tideways REST API using only GET endpoints, so an assistant can answer questions such as why checkout was slow yesterday. Tools cover listing projects and services, performance totals and layers over windows up to 24 hours, 15-minute performance summaries over up to 30 days, open or resolved issues, slow-request traces, day/week/month history reports, and detected configuration problems or code bottlenecks such as N+1 queries.
When to use it
Useful when you already run Tideways for PHP application monitoring and want an assistant to investigate slow requests, errors, slow SQL, deprecations or historical trends without opening the Tideways UI. It is read-only, so it is not for changing monitoring configuration or application code.
Requirements
A Tideways API token with the metrics, traces and errors scopes, supplied as the TIDEWAYS_TOKEN environment variable. Runs locally via npx with Node.js 22+, via Docker, or as an .mcpb bundle for Claude Desktop. Optional variables set the default project, organization, environment, service, API base URL, request timeout and log level. Network access to the Tideways API is required.
Before you install
The required TIDEWAYS_TOKEN is a credential granting read access to your Tideways performance data, including traces and errors; store it in the client's secret handling rather than in shared configuration. All tools are read-only, so nothing is written, sent or deleted. The API rate limit is per token and clock hour and is shared across all projects, and some tools cost one request per service.

Installation

In SourceWeft

  1. Open Tideways in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

Tideways MCP Server

[npm] [CI] [OpenSSF Scorecard]

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 Code
bash
claude mcp add tideways -e TIDEWAYS_TOKEN=your-token -- npx -y tideways-mcp-server

Add -s user to use it in every project.

Claude Desktop

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

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

Cursor, Gemini CLI and other clients

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

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

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.

json
{  "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}" }    }  }}
Docker

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:

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

Tools

ToolAnswers
tideways_list_projectsWhich projects, scopes and rate-limit budget does my token have?
tideways_list_servicesWhich services does a project have, and which of them serve "voucher"?
tideways_get_performanceHow is the app doing in any window of up to 24 h within the last ~30 days? Totals, layers, top transactions
tideways_get_performance_summaryRequests, errors and p95 in 15-minute buckets over up to 30 days
tideways_list_issuesWhich errors, slow SQL queries or deprecations are open, resolved or ignored?
tideways_search_tracesWhich individual requests were slow, and where did the time go?
tideways_get_historyDay, week or month report for a past date
tideways_get_observationsConfiguration 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.

VariableDefaultMeaning
TIDEWAYS_TOKENrequiredAPI token
TIDEWAYS_PROJECTthe token's only projectDefault project; with several projects and no default, pass project per call
TIDEWAYS_ORGfrom the token's projectsOrganization, to match a plain project name
TIDEWAYS_ENVAPI defaultDefault environment
TIDEWAYS_SERVICEthe project's default serviceDefault service
TIDEWAYS_BASE_URLhttps://app.tideways.io/apps/apiAPI base URL, https only
TIDEWAYS_REQUEST_TIMEOUT30000Request timeout in ms, a positive integer up to 600000
LOG_LEVELinfodebug, 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 token and clock hour, shared by all projects.
  • Tools read the project's default service unless you name one. 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

bash
npm cinpm run typecheck && npm run lint && npm run format:check && npm test   # the gatenpm 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

Source: README.md at commit 98c1714

Tools

0
Tool metadata has not been indexed yet.

Version history

1
  1. v2.0.0LatestOct 3, 2026