Parseable MCP Server

Model Context Protocol server for Parseable. 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.

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.

Quickstart

One command, interactive setup — detects Claude Desktop / Cursor, asks for your Parseable URL + credentials, writes their config files:

npx -y @parseable/parseable-mcp-server init

Restart your MCP client. Tools appear. Skip the rest of this README unless you want to configure manually.

For scripted / non-interactive setup:

npx -y @parseable/parseable-mcp-server init \
  --client claude-desktop \
  --url https://your-parseable.example.com \
  --username admin \
  --password "$PARSEABLE_PASSWORD"

Supported --client values: claude-desktop, cursor. Existing config files are backed up as <config>.bak before being modified. Other mcpServers entries are preserved.

Tools

Discovery

Tool	Purpose
`list_datasets`	List all log datasets on the server.
`get_dataset_schema`	Get column names + types for a dataset.
`get_dataset_info`	Get dataset metadata (created_at, retention, owner, time window).
`get_dataset_stats`	Get event count and storage bytes for a dataset.
`sample_events`	Return the most recent N events from a dataset (time-bounded, row-capped).

Query

Tool	Purpose
`query_sql`	Run a SQL `SELECT` over a time window. DDL/DML blocked. Auto-injects `LIMIT`.
`query_promql`	Run PromQL instant or range query against a metrics dataset. Auto-routes by `start`+`end`.

Alerts

Tool	Purpose
`list_alerts`	List all alerts with state, severity, tags.
`get_alert`	Get full config for one alert.
`list_alert_tags`	List all alert tags in use.
`enable_alert`	Enable an alert.
`disable_alert`	Disable an alert.
`evaluate_alert`	Force-evaluate an alert now. May fire real notifications.
`create_alert`	Create a new alert. Walks user through 8 questions (title, dataset, condition, window, frequency, severity, tags, targets), confirms assembled spec before submitting.

Alert targets

Notification destinations referenced by alerts. Three supported types: Slack, generic webhook, Alertmanager.

Tool	Purpose
`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.
`get_alert_target`	Get full config for one target (endpoint, headers, auth, notification interval).
`create_alert_target`	Create a new Slack/webhook/Alertmanager target.

Diagnostics

Tool	Purpose
`ping`	Check server connectivity and return version/build info (`/about`), `/liveness`, `/readiness`. Use to debug MCP-server → Parseable connection issues.
`explain_query`	Run `EXPLAIN` on a SQL query without executing it. Returns DataFusion plan for debugging slow queries, predicate pushdown, partition pruning.

RBAC (read-only)

Inspect users, roles, and effective access. No tools for creating, modifying, or deleting users/roles — RBAC mutation stays in the Parseable UI/CLI by design.

Tool	Purpose
`list_users`	List all registered users.
`get_user_roles`	Get the roles assigned to a specific user.
`list_roles`	List all role names defined on the server.
`get_role`	Get the privilege definition for a role (actions + datasets).
`get_default_role`	Get the default role assigned to new users.

These 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.

Admin (read-only)

Inspect cluster health and dataset lifecycle. No tools for mutating cluster state or retention — keep changes in UI/CLI by design.

Tool	Purpose
`get_cluster_status`	List all nodes (Prism, Querier, Ingestor, Indexer) with status. Distributed mode only.
`get_cluster_metrics`	Aggregated metrics across all nodes (ingest rate, query latency, storage). Distributed mode only.
`get_retention`	Get retention policy for a dataset.

Prerequisites

Node.js 18+
A reachable Parseable server (cloud, BYOC, or self-hosted)

Install

No install step — every MCP client invokes the server via npx, which fetches it on demand. The Quickstart above wires it into Claude Desktop / Cursor automatically. Skip ahead to Client setup below if you prefer manual config.

For local development (hacking on the server itself):

git clone https://github.com/parseablehq/parseable-mcp-server.git
cd parseable-mcp-server
npm install
npm run build
node dist/server.js

Configure

All configuration via environment variables (set in your MCP client's config file, not a .env):

Var	Required	Default	Purpose
`PARSEABLE_URL`	✅	—	Parseable server base URL, no trailing slash
`PARSEABLE_USERNAME`	✅	—	Basic auth username
`PARSEABLE_PASSWORD`	✅	—	Basic auth password
`PARSEABLE_DEFAULT_DATASET`		—	Scope a tool prompt to one dataset (advisory)
`PARSEABLE_MAX_ROWS`		1000	Hard cap on query result rows
`PARSEABLE_QUERY_TIMEOUT_MS`		30000	HTTP request timeout

Client setup

Manual config — only needed if 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.

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) · %APPDATA%\Claude\claude_desktop_config.json (Windows)

{
  "mcpServers": {
    "Parseable": {
      "command": "npx",
      "args": ["-y", "@parseable/parseable-mcp-server"],
      "env": {
        "PARSEABLE_URL": "https://your-parseable.example.com",
        "PARSEABLE_USERNAME": "admin",
        "PARSEABLE_PASSWORD": "your-password"
      }
    }
  }
}

Restart Claude Desktop. Tools appear under the hammer icon.

Claude Code

claude mcp add Parseable \
  --env PARSEABLE_URL=https://your-parseable.example.com \
  --env PARSEABLE_USERNAME=admin \
  --env PARSEABLE_PASSWORD=your-password \
  -- npx -y @parseable/parseable-mcp-server

Verify with claude mcp list.

Cursor

~/.cursor/mcp.json (global) or <project>/.cursor/mcp.json (per-project):

{
  "mcpServers": {
    "Parseable": {
      "command": "npx",
      "args": ["-y", "@parseable/parseable-mcp-server"],
      "env": {
        "PARSEABLE_URL": "https://your-parseable.example.com",
        "PARSEABLE_USERNAME": "admin",
        "PARSEABLE_PASSWORD": "your-password"
      }
    }
  }
}

Reload Cursor. Tools surface in chat.

Codex CLI

~/.codex/config.toml:

[mcp_servers.Parseable]
command = "npx"
args = ["-y", "@parseable/parseable-mcp-server"]

[mcp_servers.Parseable.env]
PARSEABLE_URL = "https://your-parseable.example.com"
PARSEABLE_USERNAME = "admin"
PARSEABLE_PASSWORD = "your-password"

VS Code (Copilot Chat)

.vscode/mcp.json in workspace, or user settings:

{
  "servers": {
    "Parseable": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@parseable/parseable-mcp-server"],
      "env": {
        "PARSEABLE_URL": "https://your-parseable.example.com",
        "PARSEABLE_USERNAME": "admin",
        "PARSEABLE_PASSWORD": "your-password"
      }
    }
  }
}

Windsurf · Continue · Cline · Zed

Same shape as Cursor's mcp.json. Consult each client's MCP docs for the exact config file path.

Try it

Once wired:

"What datasets do I have in Parseable?"
"Show schema for nginx_access."
"Run SQL: count events per status code in nginx_access over the last hour."
"Plot rate(http_requests_total[5m]) from otel_metrics over last 30 min, step 1m."
"List my alerts and which ones are disabled."
"Disable alert <id>, too noisy."
"Create an alert that fires when 5xx count in nginx_access > 50 over 5 min, severity high, notify the ops Slack channel." — the client walks the 8-step Q&A, calls list_alert_targets to pick "ops Slack" by name, then submits.
"What notification targets are configured?" — calls list_alert_targets.
"Add a Slack target pointing at https://hooks.slack.com/services/... named ops-alerts." — calls create_alert_target.

Security notes

Basic-auth credentials live in the MCP client config in plaintext. Use a Parseable user scoped to the minimum permissions the tools need.
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.
query_sql rejects DDL/DML keywords and injects a row LIMIT. Time window is mandatory.
This server makes outbound HTTPS calls to your Parseable instance only. No telemetry.

Develop

npm run dev          # tsc --watch
npm start            # node dist/server.js
npm test             # run unit tests
npm run test:watch   # vitest watch mode
npm run test:coverage
npm run lint         # biome check
npm run fix          # biome auto-fix + format
npm run format       # biome format only

CI (GitHub Actions) runs lint + build + test on every push and PR to main, on Node 20.

Alert creation flow

create_alert is Q&A-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.

When you ask the client to create an alert, it asks one question per turn:

Title — what the alert is called
Dataset — which stream to watch (calls list_datasets if unsure)
Condition — translates natural language into SQL + operator + numeric threshold, confirms back
Window — how far back each check looks (e.g. 5m, 15m, 1h)
Frequency — how often to evaluate (integer minutes)
Severity — critical / high / medium / low
Tags — comma-separated, optional
Targets — calls list_alert_targets, shows a numbered list, you pick by name

Then 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).

Roadmap

Dashboards tier (list_dashboards, get_dashboard, create_dashboard, add_dashboard_tile)
Saved filters tier
Diagnostic tools (ping, explain_query)
Admin tier (cluster status, retention, users — opt-in)
npm publish @parseable/mcp-server (one-line install via npx)
Docker image
Streamable HTTP transport for hosted mcp.parseable.com
OAuth (replace Basic auth)
Submission to modelcontextprotocol/servers registry + Smithery

License

Apache-2.0. See LICENSE.

Name		Name	Last commit message	Last commit date
Latest commit History 16 Commits
.github/workflows		.github/workflows
src		src
test		test
.env.example		.env.example
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
biome.json		biome.json
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Parseable MCP Server

Quickstart

Tools

Discovery

Query

Alerts

Alert targets

Diagnostics

RBAC (read-only)

Admin (read-only)

Prerequisites

Install

Configure

Client setup

Claude Desktop

Claude Code

Cursor

Codex CLI

VS Code (Copilot Chat)

Windsurf · Continue · Cline · Zed

Try it

Security notes

Develop

Alert creation flow

Roadmap

License

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

Parseable MCP Server

Quickstart

Tools

Discovery

Query

Alerts

Alert targets

Diagnostics

RBAC (read-only)

Admin (read-only)

Prerequisites

Install

Configure

Client setup

Claude Desktop

Claude Code

Cursor

Codex CLI

VS Code (Copilot Chat)

Windsurf · Continue · Cline · Zed

Try it

Security notes

Develop

Alert creation flow

Roadmap

License

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages