{"id":50290366,"url":"https://github.com/parseablehq/parseable-mcp-server","last_synced_at":"2026-05-28T05:34:20.679Z","repository":{"id":357775234,"uuid":"1238481347","full_name":"parseablehq/parseable-mcp-server","owner":"parseablehq","description":null,"archived":false,"fork":false,"pushed_at":"2026-05-23T11:30:15.000Z","size":160,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-28T05:34:17.622Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/parseablehq.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["parseable","operator"]}},"created_at":"2026-05-14T06:50:50.000Z","updated_at":"2026-05-23T11:30:19.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/parseablehq/parseable-mcp-server","commit_stats":null,"previous_names":["parseablehq/parseable-mcp-server"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/parseablehq/parseable-mcp-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parseablehq%2Fparseable-mcp-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parseablehq%2Fparseable-mcp-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parseablehq%2Fparseable-mcp-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parseablehq%2Fparseable-mcp-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/parseablehq","download_url":"https://codeload.github.com/parseablehq/parseable-mcp-server/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parseablehq%2Fparseable-mcp-server/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33596316,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-28T02:00:06.440Z","response_time":99,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-05-28T05:34:17.845Z","updated_at":"2026-05-28T05:34:20.674Z","avatar_url":"https://github.com/parseablehq.png","language":"TypeScript","funding_links":["https://github.com/sponsors/parseable","https://github.com/sponsors/operator"],"categories":[],"sub_categories":[],"readme":"# Parseable MCP Server\n\nModel Context Protocol server for [Parseable](https://www.parseable.com). Lets any MCP-capable client (Claude Desktop, Claude Code, Cursor, Codex, VS Code Copilot, Continue, Windsurf, Cline, Zed) discover, query, and manage Parseable datasets and alerts.\n\n\u003e **Status:** v0.2 — 27 tools across discovery, query (SQL + PromQL), alerts, alert targets, diagnostics, RBAC (read-only), and admin (read-only). Tools-only over stdio for maximum cross-client compatibility.\n\n## Quickstart\n\nOne command, interactive setup — detects Claude Desktop / Cursor, asks for your Parseable URL + credentials, writes their config files:\n\n```bash\nnpx -y @parseable/parseable-mcp-server init\n```\n\nRestart your MCP client. Tools appear. Skip the rest of this README unless you want to configure manually.\n\nFor scripted / non-interactive setup:\n\n```bash\nnpx -y @parseable/parseable-mcp-server init \\\n  --client claude-desktop \\\n  --url https://your-parseable.example.com \\\n  --username admin \\\n  --password \"$PARSEABLE_PASSWORD\"\n```\n\nSupported `--client` values: `claude-desktop`, `cursor`. Existing config files are backed up as `\u003cconfig\u003e.bak` before being modified. Other `mcpServers` entries are preserved.\n\n## Tools\n\n### Discovery\n\n| Tool                 | Purpose                                                                    |\n| -------------------- | -------------------------------------------------------------------------- |\n| `list_datasets`      | List all log datasets on the server.                                       |\n| `get_dataset_schema` | Get column names + types for a dataset.                                    |\n| `get_dataset_info`   | Get dataset metadata (created_at, retention, owner, time window).          |\n| `get_dataset_stats`  | Get event count and storage bytes for a dataset.                           |\n| `sample_events`      | Return the most recent N events from a dataset (time-bounded, row-capped). |\n\n### Query\n\n| Tool           | Purpose                                                                                    |\n| -------------- | ------------------------------------------------------------------------------------------ |\n| `query_sql`    | Run a SQL `SELECT` over a time window. DDL/DML blocked. Auto-injects `LIMIT`.              |\n| `query_promql` | Run PromQL instant or range query against a metrics dataset. Auto-routes by `start`+`end`. |\n\n### Alerts\n\n| Tool              | Purpose                                                                                                                                                                |\n| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `list_alerts`     | List all alerts with state, severity, tags.                                                                                                                            |\n| `get_alert`       | Get full config for one alert.                                                                                                                                         |\n| `list_alert_tags` | List all alert tags in use.                                                                                                                                            |\n| `enable_alert`    | Enable an alert.                                                                                                                                                       |\n| `disable_alert`   | Disable an alert.                                                                                                                                                      |\n| `evaluate_alert`  | Force-evaluate an alert now. **May fire real notifications.**                                                                                                          |\n| `create_alert`    | Create a new alert. Walks user through 8 questions (title, dataset, condition, window, frequency, severity, tags, targets), confirms assembled spec before submitting. |\n\n### Alert targets\n\nNotification destinations referenced by alerts. Three supported types: **Slack**, **generic webhook**, **Alertmanager**.\n\n| Tool                  | Purpose                                                                                                                                            |\n| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `list_alert_targets`  | List all configured targets with ID, name, type. Called automatically by `create_alert` so the user picks targets by name instead of typing UUIDs. |\n| `get_alert_target`    | Get full config for one target (endpoint, headers, auth, notification interval).                                                                   |\n| `create_alert_target` | Create a new Slack/webhook/Alertmanager target.                                                                                                    |\n\n### Diagnostics\n\n| Tool            | Purpose                                                                                                                                               |\n| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `ping`          | Check server connectivity and return version/build info (`/about`), `/liveness`, `/readiness`. Use to debug MCP-server → Parseable connection issues. |\n| `explain_query` | Run `EXPLAIN` on a SQL query without executing it. Returns DataFusion plan for debugging slow queries, predicate pushdown, partition pruning.         |\n\n### RBAC (read-only)\n\nInspect users, roles, and effective access. **No tools for creating, modifying, or deleting users/roles** — RBAC mutation stays in the Parseable UI/CLI by design.\n\n| Tool               | Purpose                                                       |\n| ------------------ | ------------------------------------------------------------- |\n| `list_users`       | List all registered users.                                    |\n| `get_user_roles`   | Get the roles assigned to a specific user.                    |\n| `list_roles`       | List all role names defined on the server.                    |\n| `get_role`         | Get the privilege definition for a role (actions + datasets). |\n| `get_default_role` | Get the default role assigned to new users.                   |\n\nThese compose for permission audits: \"Does user X have write access to dataset Y?\" → call `get_user_roles(X)` → for each role call `get_role` → check if `Ingest` or `PutAlert` privilege covers Y.\n\n### Admin (read-only)\n\nInspect cluster health and dataset lifecycle. **No tools for mutating cluster state or retention** — keep changes in UI/CLI by design.\n\n| Tool                  | Purpose                                                                                           |\n| --------------------- | ------------------------------------------------------------------------------------------------- |\n| `get_cluster_status`  | List all nodes (Prism, Querier, Ingestor, Indexer) with status. Distributed mode only.            |\n| `get_cluster_metrics` | Aggregated metrics across all nodes (ingest rate, query latency, storage). Distributed mode only. |\n| `get_retention`       | Get retention policy for a dataset.                                                               |\n\n## Prerequisites\n\n- Node.js 18+\n- A reachable Parseable server (cloud, BYOC, or self-hosted)\n\n## Install\n\nNo install step — every MCP client invokes the server via `npx`, which fetches it on demand. The [Quickstart](#quickstart) above wires it into Claude Desktop / Cursor automatically. Skip ahead to **Client setup** below if you prefer manual config.\n\nFor local development (hacking on the server itself):\n\n```bash\ngit clone https://github.com/parseablehq/parseable-mcp-server.git\ncd parseable-mcp-server\nnpm install\nnpm run build\nnode dist/server.js\n```\n\n## Configure\n\nAll configuration via environment variables (set in your MCP client's config file, not a `.env`):\n\n| Var                          | Required | Default | Purpose                                       |\n| ---------------------------- | -------- | ------- | --------------------------------------------- |\n| `PARSEABLE_URL`              | ✅       | —       | Parseable server base URL, no trailing slash  |\n| `PARSEABLE_USERNAME`         | ✅       | —       | Basic auth username                           |\n| `PARSEABLE_PASSWORD`         | ✅       | —       | Basic auth password                           |\n| `PARSEABLE_DEFAULT_DATASET`  |          | —       | Scope a tool prompt to one dataset (advisory) |\n| `PARSEABLE_MAX_ROWS`         |          | 1000    | Hard cap on query result rows                 |\n| `PARSEABLE_QUERY_TIMEOUT_MS` |          | 30000   | HTTP request timeout                          |\n\n## Client setup\n\nManual config — only needed if [Quickstart](#quickstart) doesn't cover your client (Claude Code, Codex, VS Code, Windsurf, Continue, Cline, Zed). The command and args are the same for every client — only the config file location and syntax differ.\n\n### Claude Desktop\n\n`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) · `%APPDATA%\\Claude\\claude_desktop_config.json` (Windows)\n\n```json\n{\n  \"mcpServers\": {\n    \"Parseable\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@parseable/parseable-mcp-server\"],\n      \"env\": {\n        \"PARSEABLE_URL\": \"https://your-parseable.example.com\",\n        \"PARSEABLE_USERNAME\": \"admin\",\n        \"PARSEABLE_PASSWORD\": \"your-password\"\n      }\n    }\n  }\n}\n```\n\nRestart Claude Desktop. Tools appear under the hammer icon.\n\n### Claude Code\n\n```bash\nclaude mcp add Parseable \\\n  --env PARSEABLE_URL=https://your-parseable.example.com \\\n  --env PARSEABLE_USERNAME=admin \\\n  --env PARSEABLE_PASSWORD=your-password \\\n  -- npx -y @parseable/parseable-mcp-server\n```\n\nVerify with `claude mcp list`.\n\n### Cursor\n\n`~/.cursor/mcp.json` (global) or `\u003cproject\u003e/.cursor/mcp.json` (per-project):\n\n```json\n{\n  \"mcpServers\": {\n    \"Parseable\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@parseable/parseable-mcp-server\"],\n      \"env\": {\n        \"PARSEABLE_URL\": \"https://your-parseable.example.com\",\n        \"PARSEABLE_USERNAME\": \"admin\",\n        \"PARSEABLE_PASSWORD\": \"your-password\"\n      }\n    }\n  }\n}\n```\n\nReload Cursor. Tools surface in chat.\n\n### Codex CLI\n\n`~/.codex/config.toml`:\n\n```toml\n[mcp_servers.Parseable]\ncommand = \"npx\"\nargs = [\"-y\", \"@parseable/parseable-mcp-server\"]\n\n[mcp_servers.Parseable.env]\nPARSEABLE_URL = \"https://your-parseable.example.com\"\nPARSEABLE_USERNAME = \"admin\"\nPARSEABLE_PASSWORD = \"your-password\"\n```\n\n### VS Code (Copilot Chat)\n\n`.vscode/mcp.json` in workspace, or user settings:\n\n```json\n{\n  \"servers\": {\n    \"Parseable\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@parseable/parseable-mcp-server\"],\n      \"env\": {\n        \"PARSEABLE_URL\": \"https://your-parseable.example.com\",\n        \"PARSEABLE_USERNAME\": \"admin\",\n        \"PARSEABLE_PASSWORD\": \"your-password\"\n      }\n    }\n  }\n}\n```\n\n### Windsurf · Continue · Cline · Zed\n\nSame shape as Cursor's `mcp.json`. Consult each client's MCP docs for the exact config file path.\n\n## Try it\n\nOnce wired:\n\n- _\"What datasets do I have in Parseable?\"_\n- _\"Show schema for `nginx_access`.\"_\n- _\"Run SQL: count events per status code in `nginx_access` over the last hour.\"_\n- _\"Plot rate(http_requests_total[5m]) from `otel_metrics` over last 30 min, step 1m.\"_\n- _\"List my alerts and which ones are disabled.\"_\n- _\"Disable alert `\u003cid\u003e`, too noisy.\"_\n- _\"Create an alert that fires when 5xx count in `nginx_access` \u003e 50 over 5 min, severity high, notify the ops Slack channel.\"_ — the client walks the 8-step Q\u0026A, calls `list_alert_targets` to pick \"ops Slack\" by name, then submits.\n- _\"What notification targets are configured?\"_ — calls `list_alert_targets`.\n- _\"Add a Slack target pointing at `https://hooks.slack.com/services/...` named ops-alerts.\"_ — calls `create_alert_target`.\n\n## Security notes\n\n- Basic-auth credentials live in the MCP client config in plaintext. Use a Parseable user scoped to the minimum permissions the tools need.\n- Mutating tools (`enable_alert`, `disable_alert`, `evaluate_alert`, `create_alert`) are NOT gated by env flag — every MCP client already shows per-call approval UI. `evaluate_alert` can fire real notifications; review the call before approving.\n- `query_sql` rejects DDL/DML keywords and injects a row `LIMIT`. Time window is mandatory.\n- This server makes outbound HTTPS calls to your Parseable instance only. No telemetry.\n\n## Develop\n\n```bash\nnpm run dev          # tsc --watch\nnpm start            # node dist/server.js\nnpm test             # run unit tests\nnpm run test:watch   # vitest watch mode\nnpm run test:coverage\nnpm run lint         # biome check\nnpm run fix          # biome auto-fix + format\nnpm run format       # biome format only\n```\n\nCI (GitHub Actions) runs lint + build + test on every push and PR to `main`, on Node 20.\n\n## Alert creation flow\n\n`create_alert` is Q\u0026A-driven via tool description — works on every MCP client (Claude Desktop, Claude Code, Cursor, Codex, VS Code, etc.) since it relies only on the client reading the tool description, not on client-specific UI primitives.\n\nWhen you ask the client to create an alert, it asks one question per turn:\n\n1. **Title** — what the alert is called\n2. **Dataset** — which stream to watch (calls `list_datasets` if unsure)\n3. **Condition** — translates natural language into SQL + operator + numeric threshold, confirms back\n4. **Window** — how far back each check looks (e.g. `5m`, `15m`, `1h`)\n5. **Frequency** — how often to evaluate (integer minutes)\n6. **Severity** — `critical` / `high` / `medium` / `low`\n7. **Tags** — comma-separated, optional\n8. **Targets** — calls `list_alert_targets`, shows a numbered list, you pick by name\n\nThen it shows the fully assembled JSON spec, you confirm, and it submits via `create_alert`. The same flow works for `create_alert_target` (asks name → type → endpoint → type-specific fields).\n\n## Roadmap\n\n- Dashboards tier (`list_dashboards`, `get_dashboard`, `create_dashboard`, `add_dashboard_tile`)\n- Saved filters tier\n- Diagnostic tools (`ping`, `explain_query`)\n- Admin tier (cluster status, retention, users — opt-in)\n- `npm publish @parseable/mcp-server` (one-line install via `npx`)\n- Docker image\n- Streamable HTTP transport for hosted `mcp.parseable.com`\n- OAuth (replace Basic auth)\n- Submission to `modelcontextprotocol/servers` registry + Smithery\n\n## License\n\nApache-2.0. See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fparseablehq%2Fparseable-mcp-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fparseablehq%2Fparseable-mcp-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fparseablehq%2Fparseable-mcp-server/lists"}