Parseable MCP Server

Model Context Protocol server for Parseable. Lets any MCP-capable client (Claude Desktop, Claude Code, Cursor, VS Code Copilot, Windsurf, Continue, Cline, Zed, Codex) discover, query, and manage Parseable datasets and alerts using natural language.

Two transports:

Mode	Transport	Auth	Use when
`stdio`	Stdin/stdout	API key via env vars	Claude Desktop, Cursor, VS Code, local clients
`http`	Streamable HTTP	Cloud API key, or self-hosted URL + API key	Hosted deployments and remote clients

Quickstart — stdio (local)

One command — interactive setup, detects Claude Desktop / Cursor, writes config files:

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

Restart your MCP client. Tools appear. Done.

Scripted:

npx -y @parseable/parseable-mcp-server init \
  --client claude-desktop \
  --url https://your-parseable.example.com \
  --api-key "$PARSEABLE_API_KEY"

Supported --client values: claude-desktop, cursor.

Cursor Marketplace plugin

The repository also contains a native Cursor plugin manifest. Marketplace installs connect to https://mcp.parseable.com/mcp and read credentials from the environment.

Set these variables before starting Cursor:

export PARSEABLE_URL="https://your-parseable.example.com"
export PARSEABLE_API_KEY="your-api-key"
export PARSEABLE_MODE="self-hosted"

PARSEABLE_API_KEY and PARSEABLE_MODE are required by the Cursor plugin. Use PARSEABLE_MODE=cloud and omit PARSEABLE_URL for Parseable Cloud. Use PARSEABLE_MODE=self-hosted with PARSEABLE_URL for self-hosted Parseable.

# Parseable Cloud
export PARSEABLE_MODE="cloud"
export PARSEABLE_API_KEY="your-cloud-api-key"
unset PARSEABLE_URL

Then install the Parseable plugin from the Cursor Marketplace. If Cursor was opened from the macOS dock or another GUI launcher that does not inherit shell variables, use the interactive setup instead:

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

Plugin metadata lives in .cursor-plugin/plugin.json; its MCP connection configuration lives in mcp.json. Keep the plugin version aligned with the npm package version when releasing.

Quickstart — HTTP (hosted)

HTTP mode serves a setup page and MCP endpoint from one process. Cloud clients supply an API key. Self-hosted clients supply their Parseable URL and API key.

1. Set env vars

# .env
PORT=8787

2. Run

# From source
npm run build:all
node dist/server.js http

# Docker
docker build -t parseable-mcp-server .
docker run -p 8787:8787 --env-file .env parseable-mcp-server

3. Connect from Claude

Claude Desktop → Settings → Connectors → Add custom connector
Name: Parseable
URL: https://mcp.your-domain.com/mcp
Header X-Parseable-URL: https://your-parseable.example.com
Header X-API-Key: your Parseable API key
Click Add → Connect

4. Connect from Claude Code

claude mcp add --transport http parseable https://mcp.your-domain.com/mcp --scope user \
  --header "X-Parseable-URL: https://your-parseable.example.com" \
  --header "X-API-Key: $PARSEABLE_API_KEY"

5. Connect from Cursor / VS Code

{
  "mcpServers": {
    "parseable": {
      "type": "http",
      "url": "https://mcp.your-domain.com/mcp",
      "headers": {
        "X-Parseable-URL": "https://your-parseable.example.com",
        "X-API-Key": "your-parseable-api-key"
      }
    }
  }
}

HTTP authentication

Each POST /mcp request requires X-API-Key and supports two modes:

Mode	Headers
Cloud	`X-Parseable-Mode: cloud`, `X-API-Key`
Self-hosted (default)	`X-Parseable-URL`, `X-API-Key`

X-Parseable-Mode is checked first when present. Omitting it selects self-hosted mode; clients do not need to send X-Parseable-Mode: self-hosted. In cloud mode, server validates API key with Parseable Cloud, caches returned URL and tenant routing in a bounded in-memory LRU for 24 hours, and sends x-p-tenant on Parseable requests. Cache is disposable; misses and process restarts resolve through Cloud again.

For self-hosted mode, HTTP server validates supplied URL and forwards API key to that Parseable instance. By default, private and loopback Parseable URLs are rejected to limit SSRF. Set PARSEABLE_MCP_ALLOW_PRIVATE=true only for trusted deployments that need private network targets.

Environment variables

stdio mode

Var	Required	Default	Purpose
`PARSEABLE_URL`	✅	—	Parseable base URL
`PARSEABLE_API_KEY`	✅	—	API key for self-hosted Parseable
`PARSEABLE_DEFAULT_DATASET`		—	Advisory default dataset
`PARSEABLE_MAX_ROWS`		1000	Hard cap on query rows
`PARSEABLE_QUERY_TIMEOUT_MS`		30000	HTTP timeout (ms)

HTTP mode

Var	Required	Default	Purpose
`PORT`		8787	HTTP listen port
`PARSEABLE_MCP_ALLOW_PRIVATE`		false	Permit private/loopback Parseable URLs supplied in request headers
`PARSEABLE_ORCHESTRATOR_URL`	Cloud only	-	Parseable Cloud orchestrator base URL
`PARSEABLE_CLOUD_AUTH_TOKEN`	Cloud only	-	Service bearer token for API-key validation
`PARSEABLE_CLOUD_CACHE_TTL_SECONDS`		86400	Cloud routing LRU TTL
`PARSEABLE_CLOUD_CACHE_MAX_ENTRIES`		10000	Maximum cached cloud API-key routes
`PARSEABLE_CLOUD_VALIDATE_TIMEOUT_MS`		10000	Cloud validation timeout

OpenTelemetry (optional)

Var	Default	Purpose
`PARSEABLE_OTEL_ENABLED`	false	Enable trace export to Parseable
`PARSEABLE_OTEL_ENDPOINT`	—	Parseable OTLP endpoint
`PARSEABLE_OTEL_USERNAME`	—	Basic auth for OTLP
`PARSEABLE_OTEL_PASSWORD`	—	Basic auth for OTLP
`PARSEABLE_OTEL_TRACES_STREAM`	mcp-traces	Stream name for traces
`PARSEABLE_OTEL_DEBUG`	false	Log OTLP export errors

Copy .env.example → .env for a full template.

Tools

Discovery

Tool	Purpose
`list_datasets`	List all log datasets
`get_dataset_schema`	Column names + types
`get_dataset_info`	Metadata (created_at, retention, time window)
`get_dataset_stats`	Event count and storage bytes
`sample_events`	Most recent N events (time-bounded, row-capped)

Query

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

Alerts

Tool	Purpose
`list_alerts`	List all alerts with state, severity, tags
`get_alert`	Full config for one alert
`list_alert_tags`	All alert tags in use
`enable_alert`	Enable an alert
`disable_alert`	Disable an alert
`evaluate_alert`	Force-evaluate now. May fire real notifications.
`create_alert`	Create alert via guided Q&A (8 questions, confirms before submit)

Alert targets

Tool	Purpose
`list_alert_targets`	List targets (Slack, webhook, Alertmanager)
`get_alert_target`	Full config for one target
`create_alert_target`	Create a new Slack / webhook / Alertmanager target

Diagnostics

Tool	Purpose
`ping`	Check connectivity, return version + health
`explain_query`	`EXPLAIN` a SQL query without executing it

RBAC (read-only)

Tool	Purpose
`list_users`	List all users
`get_user_roles`	Roles for a specific user
`list_roles`	All role names
`get_role`	Privilege definition for a role
`get_default_role`	Default role for new users

Admin (read-only)

Tool	Purpose
`get_cluster_status`	All nodes with status (distributed mode)
`get_cluster_metrics`	Aggregated ingest/query/storage metrics
`get_retention`	Retention policy for a dataset

Client setup — stdio

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "Parseable": {
      "command": "npx",
      "args": ["-y", "@parseable/parseable-mcp-server"],
      "env": {
        "PARSEABLE_URL": "https://your-parseable.example.com",
        "PARSEABLE_API_KEY": "your-api-key"
      }
    }
  }
}

Claude Code

claude mcp add Parseable \
  --env PARSEABLE_URL=https://your-parseable.example.com \
  --env PARSEABLE_API_KEY=your-api-key \
  -- npx -y @parseable/parseable-mcp-server

Cursor

~/.cursor/mcp.json:

{
  "mcpServers": {
    "Parseable": {
      "command": "npx",
      "args": ["-y", "@parseable/parseable-mcp-server"],
      "env": {
        "PARSEABLE_URL": "https://your-parseable.example.com",
        "PARSEABLE_API_KEY": "your-api-key"
      }
    }
  }
}

VS Code

.vscode/mcp.json:

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

Development

git clone https://github.com/parseablehq/parseable-mcp-server.git
cd parseable-mcp-server
npm install
cp .env.example .env    # fill in your values

# Build
npm run build           # server only (tsc)
npm run build:ui        # React UI only (vite)
npm run build:all       # both

# Run
node dist/server.js         # stdio mode
node dist/server.js http    # HTTP mode (port 8787)

# Dev
npm run dev             # tsc --watch
npm run dev:ui          # vite dev server (proxies API to :8787)
npm test
npm run lint
npm run fix             # biome auto-fix

CI (GitHub Actions) runs lint + build:all + test on every push/PR to main on Node 22. On merge to main, Docker image is published to ghcr.io/parseablehq/parseable-mcp-server.

Security

Parseable API keys live in MCP client configuration. Use keys scoped to minimum required permissions.
HTTP clients send credentials in X-Parseable-URL and X-API-Key; always use HTTPS for remote deployments.
query_sql blocks DDL/DML and enforces a row LIMIT. Time window is mandatory.
evaluate_alert can fire real notifications — review the call before approving.
No telemetry. Outbound calls go only to the Parseable instance configured by the user.

License

Apache-2.0. See LICENSE.

Name		Name	Last commit message	Last commit date
Latest commit History 42 Commits
.cursor-plugin		.cursor-plugin
.github/workflows		.github/workflows
assets		assets
src		src
test		test
.dockerignore		.dockerignore
.env.docker.example		.env.docker.example
.env.example		.env.example
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
Dockerfile.mcp		Dockerfile.mcp
LICENSE		LICENSE
README.md		README.md
biome.json		biome.json
docker-compose.yml		docker-compose.yml
mcp.json		mcp.json
package-lock.json		package-lock.json
package.json		package.json
server.json		server.json
tsconfig.json		tsconfig.json
vite.config.ts		vite.config.ts
vitest.config.ts		vitest.config.ts

Navigation Menu

Uh oh!

Repository files navigation

Parseable MCP Server

Quickstart — stdio (local)

Cursor Marketplace plugin

Quickstart — HTTP (hosted)

1. Set env vars

2. Run

3. Connect from Claude

4. Connect from Claude Code

5. Connect from Cursor / VS Code

HTTP authentication

Environment variables

stdio mode

HTTP mode

OpenTelemetry (optional)

Tools

Discovery

Query

Alerts

Alert targets

Diagnostics

RBAC (read-only)

Admin (read-only)

Client setup — stdio

Claude Desktop

Claude Code

Cursor

VS Code

Development

Security

License

About

Releases

Contributors

Languages

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

Parseable MCP Server

Quickstart — stdio (local)

Cursor Marketplace plugin

Quickstart — HTTP (hosted)

1. Set env vars

2. Run

3. Connect from Claude

4. Connect from Claude Code

5. Connect from Cursor / VS Code

HTTP authentication

Environment variables

stdio mode

HTTP mode

OpenTelemetry (optional)

Tools

Discovery

Query

Alerts

Alert targets

Diagnostics

RBAC (read-only)

Admin (read-only)

Client setup — stdio

Claude Desktop

Claude Code

Cursor

VS Code

Development

Security

License

About

Resources

Contributing

Stars

Watchers

Forks

Releases

Contributors

Languages