Parseable

Parseable MCP 服务

Parseable 的 Model Context Protocol 服务。让任何支持 MCP 的客户端（Claude Desktop、Claude Code、Cursor、VS Code Copilot、Windsurf、Continue、Cline、Zed、Codex）都能通过自然语言发现、查询和管理 Parseable 数据集与告警。

两种传输方式：

模式	传输方式	认证	适用场景
stdio	标准输入/标准输出	通过环境变量提供 API 密钥	Claude Desktop、Cursor、VS Code、本地客户端
http	Streamable HTTP	Cloud API 密钥，或可自托管实例的 URL + API 密钥	托管部署和远程客户端

---

快速开始 — stdio（本地）

一条命令即可完成交互式设置、检测 Claude Desktop / Cursor 并写入配置文件：

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

重启 MCP 客户端。工具即可使用。完成。

脚本化设置：

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

支持的 --client 值：claude-desktop、cursor。

Cursor Marketplace 插件

仓库还包含原生 Cursor 插件清单。通过 Marketplace 安装后，插件会连接到 https://mcp.parseable.com/mcp，并从环境变量读取凭据。

启动 Cursor 前，请设置以下变量：

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

Cursor 插件需要 PARSEABLE_API_KEY 和 PARSEABLE_MODE。对于 Parseable Cloud，请使用 PARSEABLE_MODE=cloud，并省略 PARSEABLE_URL。对于可自托管的 Parseable，请使用 PARSEABLE_MODE=self-hosted 和 PARSEABLE_URL。

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

然后从 Cursor Marketplace 安装 Parseable 插件。如果 Cursor 是从 macOS 程序坞或其他不会继承 Shell 变量的图形界面启动器打开的，请改用交互式设置：

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

插件元数据位于 .cursor-plugin/plugin.json；其 MCP 连接配置位于 mcp.json。发布时，请确保插件版本与 npm 包版本一致。

---

快速开始 — HTTP（托管）

HTTP 模式通过一个进程提供设置页面和 MCP 端点。Cloud 客户端提供 API 密钥。可自托管实例的客户端提供其 Parseable URL 和 API 密钥。

1. 设置环境变量

# .env
PORT=8787

2. 运行

# 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. 从 Claude 连接

• Claude Desktop → 设置 → 连接器 → 添加自定义连接器
• 名称：Parseable
• URL：https://mcp.your-domain.com/mcp
• 请求头 X-Parseable-URL：https://your-parseable.example.com
• 请求头 X-API-Key：你的 Parseable API 密钥
• 点击添加 → 连接

4. 从 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. 从 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 身份验证

每个 POST /mcp 请求都需要 X-API-Key，并支持两种模式：

模式	请求头
Cloud	X-Parseable-Mode: cloud、X-API-Key
可自托管（默认）	X-Parseable-URL、X-API-Key

如果存在 X-Parseable-Mode，会优先检查它。省略此项即选择可自托管模式；客户端无需发送 X-Parseable-Mode: self-hosted。在 Cloud 模式下，服务会使用 Parseable Cloud 验证 API 密钥，并将返回的 URL 和租户路由信息缓存在有容量限制的内存 LRU 缓存中，缓存有效期为 24 小时，然后在发送给 Parseable 的请求中附加 x-p-tenant。缓存可随时丢弃；缓存未命中和进程重启时，都会再次通过 Cloud 解析。

在可自托管模式下，HTTP 服务会验证提供的 URL，并将 API 密钥转发到对应的 Parseable 实例。默认情况下，为限制 SSRF 风险，会拒绝指向私有网络和环回地址的 Parseable URL。只有在可信部署需要访问私有网络目标时，才设置 PARSEABLE_MCP_ALLOW_PRIVATE=true。

---

环境变量

stdio 模式

变量	必填	默认值	用途
PARSEABLE_URL	✅	—	Parseable 基础 URL
PARSEABLE_API_KEY	✅	—	可自托管 Parseable 的 API 密钥
PARSEABLE_QUERY_TIMEOUT_MS		30000	HTTP 超时时间（毫秒）

HTTP 模式

变量	必填	默认值	用途
PORT		8787	HTTP 监听端口
PARSEABLE_MCP_ALLOW_PRIVATE		false	允许请求头中提供私有/环回 Parseable URL
PARSEABLE_ORCHESTRATOR_URL	仅限 Cloud	-	Parseable Cloud 编排器基础 URL
PARSEABLE_CLOUD_AUTH_TOKEN	仅限 Cloud	-	用于验证 API 密钥的服务 Bearer 令牌
PARSEABLE_CLOUD_CACHE_TTL_SECONDS		86400	Cloud 路由 LRU 缓存 TTL
PARSEABLE_CLOUD_CACHE_MAX_ENTRIES		10000	缓存的 Cloud API 密钥路由数上限
PARSEABLE_CLOUD_VALIDATE_TIMEOUT_MS		10000	Cloud 验证超时时间

OpenTelemetry（可选）

变量	默认值	用途
PARSEABLE_OTEL_ENABLED	false	启用向 Parseable 导出追踪数据
PARSEABLE_OTEL_ENDPOINT	—	Parseable OTLP 端点
PARSEABLE_OTEL_USERNAME	—	OTLP 基本身份验证
PARSEABLE_OTEL_PASSWORD	—	OTLP 基本身份验证
PARSEABLE_OTEL_TRACES_STREAM	mcp-traces	追踪数据的流名称
PARSEABLE_OTEL_DEBUG	false	记录 OTLP 导出错误

将 .env.example 复制为 .env，即可获得完整模板。

---

工具

工具由连接的 Parseable 实例提供，而不是由此适配器提供。对于 MCP tools/list，适配器会从 GET /api/prism/v1/llm/tools/list 获取特定版本的目录。 OSS、Enterprise 和 Cloud 可能提供不同的工具集。

适配器会按服务器提供的 max-age 缓存目录， 并使用 ETag 重新验证。MCP tools/call 请求会转发到 POST /api/prism/v1/llm/tools/call，由 Parseable 验证参数、 应用 RBAC、执行工具并返回 MCP CallToolResult。

---

客户端设置 — 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"
      }
    }
  }
}

---

开发

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）会在每次推送或向 main 提交 PR 时，使用 Node 22 运行 lint、build:all 和测试。合并到 main 后，Docker 镜像会发布到 ghcr.io/parseablehq/parseable-mcp-server。

---

安全

• Parseable API 密钥存放在 MCP 客户端配置中。请使用权限范围符合最低需求的密钥。
• HTTP 客户端通过 X-Parseable-URL 和 X-API-Key 发送凭据；远程部署务必使用 HTTPS。
• query_sql 会阻止 DDL/DML 并强制设置行数 LIMIT。必须指定时间范围。
• evaluate_alert 可能会触发实际通知——批准前请检查调用内容。
• 不收集遥测数据。对外调用仅发送到用户配置的 Parseable 实例。

---

许可证

Apache-2.0。请参阅 LICENSE。