Read-only access to Tideways PHP performance monitoring: performance, issues, traces, history.
io.github.abuhamza/tideways-mcp-server MCP Server
The io.github.abuhamza/tideways-mcp-server provides read-only access to Tideways PHP performance monitoring. It exposes data related to performance, issues, traces, and history, enabling clients to retrieve monitoring information without modifying any server-side state.
🛠️ Key Features
Read-only access to Tideways PHP performance monitoring
Access to performance data
Access to issues
Access to traces
Access to history
🚀 Use Cases
Retrieve Tideways performance metrics for analysis
Inspect reported issues detected by Tideways
View execution traces captured by Tideways
Access historical monitoring data
⚡ Developer Benefits
Safe integration via read-only access
Structured access to performance, issues, traces, and history
Suitable for tooling that needs monitoring readbacks
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.
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
Which projects, scopes and rate-limit budget does my token have?
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_performance_summary
Requests, errors and p95 in 15-minute buckets over up to 30 days
tideways_list_issues
Which errors, slow SQL queries or deprecations are open, resolved or ignored?
tideways_search_traces
Which individual requests were slow, 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 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 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
