Tideways

io.github.abuhamzav2.0.0更新于 Oct 3, 2026

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

已验证STDIO仅桌面Security & MonitoringData & Analytics

概览

AI 生成的概览

只读访问 Tideways PHP 性能监控，让助手查询性能、问题、追踪和历史数据。

功能
仅使用 GET 端点封装 Tideways REST API，因此助手可以回答诸如“昨天结账为什么慢”之类的问题。工具涵盖列出项目和服务、最长 24 小时窗口内的性能总量与分层、最长 30 天的 15 分钟性能摘要、未解决或已解决的问题、慢请求追踪、按日/周/月的历史报告，以及检测到的配置问题和代码瓶颈（例如 N+1 查询）。
适用场景
当你已经使用 Tideways 监控 PHP 应用，并希望助手在不打开 Tideways 界面的情况下排查慢请求、错误、慢 SQL、弃用警告或历史趋势时适用。它是只读的，因此不适合修改监控配置或应用代码。
运行要求
需要一个具有 metrics、traces 和 errors 权限范围的 Tideways API 令牌，通过 TIDEWAYS_TOKEN 环境变量提供。可通过 npx 配合 Node.js 22+ 本地运行，也可用 Docker 或 Claude Desktop 的 .mcpb 包运行。可选变量用于设置默认项目、组织、环境、服务、API 基础地址、请求超时和日志级别。需要能访问 Tideways API 的网络。
安装前请注意
必需的 TIDEWAYS_TOKEN 是授予 Tideways 性能数据（包括追踪和错误）读取权限的凭据，应存放在客户端的密钥管理中，而不是共享配置里。所有工具均为只读，不会写入、发送或删除任何内容。API 速率限制按令牌和整点小时计算，并在所有项目间共享，部分工具每个服务会消耗一次请求。

安装

在 SourceWeft 中

  1. 打开 控制台中的 Tideways，将其添加到工作区。
  2. 为需要使用其工具的对话启用该服务。

Desktop only，通过 STDIO。 STDIO 服务会启动本地进程，因此需要 SourceWeft 桌面宿主。

其他 MCP 客户端

参照 仓库 中的启动说明。

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

来源：README.md，提交 98c1714

工具

0
工具元数据尚未被收录。

版本历史

1
  1. v2.0.0最新Oct 3, 2026