Parseable MCP Server

Model Context Protocol server for Parseable. Позволяет любому MCP-совместимому клиенту (Claude Desktop, Claude Code, Cursor, VS Code Copilot, Windsurf, Continue, Cline, Zed, Codex) обнаруживать, запрашивать и управлять наборами данных и оповещениями Parseable с помощью естественного языка.

Две транспортные схемы:

Режим	Транспорт	Аутентификация	Использовать когда
stdio	Stdin/stdout	API key через env vars	Claude Desktop, Cursor, VS Code, локальные клиенты
http	Streamable HTTP	Cloud API key, или self-hosted URL + API key	Развертывания в облаке и удаленные клиенты

Quickstart — 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"

PARSEABLE_API_KEY и PARSEABLE_MODE необходимы плагину Cursor. Используйте PARSEABLE_MODE=cloud и опустите PARSEABLE_URL для Parseable Cloud. Используйте PARSEABLE_MODE=self-hosted с PARSEABLE_URL для self-hosted Parseable.

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

Затем установите плагин Parseable из Cursor Marketplace. Если Cursor был открыт из дока macOS или другого GUI-лаунача, который не унаследовал переменные окружения, используйте интерактивный setup:

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

Метаданные плагина хранятся в .cursor-plugin/plugin.json; его конфигурация MCP-соединения — в mcp.json. Поддерживайте версию плагина в соответствие с версией npm-пакета при выпуске.

Quickstart — HTTP (hosted)

HTTP-режим предоставляет страницу настройки и MCP endpoint в одном процессе. Клиенты облака передают API key. Самохостинговые клиенты передают свой Parseable URL и API key.

1. Установите переменные окружения

# .env
PORT=8787

2. Запуск

# Из исходников
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 → 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: ваш API-ключ Parseable
Нажмите Add → Connect

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 authentication

Каждый запрос POST /mcp требует X-API-Key и поддерживает две схемы:

Режим	Заголовки
Cloud	X-Parseable-Mode: cloud, X-API-Key
Self-hosted (по умолчанию)	X-Parseable-URL, X-API-Key

X-Parseable-Mode проверяется первым, если он присутствует. Пропуск его выбирает self-hosted-режим; клиенты не обязаны отправлять X-Parseable-Mode: self-hosted. В облачном режиме сервер валидирует API-key через Parseable Cloud, кэширует возвращённый URL и маршрутизацию тенанта в ограниченном in-memory LRU на 24 часа и отправляет x-p-tenant в запросах Parseable. Кэш выбрасывается; пропуски и перезапуски процесса снова вынуждают обращаться к Cloud.

Для self-hosted-режима HTTP-сервер валидирует переданный URL и пересылает API key в соответствующий экземпляр Parseable. По умолчанию приватные и loopback-URL Parseable отклоняются для ограничения SSRF. Устанавливайте PARSEABLE_MCP_ALLOW_PRIVATE=true только для доверенных развёртываний, которым нужны приватные сетевые цели.

Переменные окружения

stdio mode

Переменная	Обязательна	По умолчанию	Назначение
PARSEABLE_URL	✅	—	Базовый URL Parseable
PARSEABLE_API_KEY	✅	—	API-key для self-hosted Parseable
PARSEABLE_DEFAULT_DATASET		—	Рекомендованный набор данных по умолчанию
PARSEABLE_MAX_ROWS		1000	Жесткий предел на количество строк в запросе
PARSEABLE_QUERY_TIMEOUT_MS		30000	Таймаут HTTP (мс)

HTTP mode

Переменная	Обязательна	По умолчанию	Назначение
PORT		8787	HTTP-порт прослушивания
PARSEABLE_MCP_ALLOW_PRIVATE		false	Разрешать приватные/loopback URL Parseable в заголовках запросов
PARSEABLE_ORCHESTRATOR_URL	Тільки Cloud	-	Базовый URL оркестратора Parseable Cloud
PARSEABLE_CLOUD_AUTH_TOKEN	Cloud only	-	Токен сервиса для валидации API-key
PARSEABLE_CLOUD_CACHE_TTL_SECONDS		86400	TTL LRU маршрутизации в Cloud
PARSEABLE_CLOUD_CACHE_MAX_ENTRIES		10000	Максимальное число закэшированных маршрутов API-key в Cloud
PARSEABLE_CLOUD_VALIDATE_TIMEOUT_MS		10000	Таймаут валидации в Cloud

OpenTelemetry (optional)

Переменная	По умолчанию	Назначение
PARSEABLE_OTEL_ENABLED	false	Включение экспорта трассирования в Parseable
PARSEABLE_OTEL_ENDPOINT	—	OTLP-ендпоинт Parseable
PARSEABLE_OTEL_USERNAME	—	Базовая аутентификация для OTLP
PARSEABLE_OTEL_PASSWORD	—	Базовая аутентификация для OTLP
PARSEABLE_OTEL_TRACES_STREAM	mcp-traces	Имя потока для трассировок
PARSEABLE_OTEL_DEBUG	false	Логирование ошибок экспорта OTLP

Скопируйте .env.example → .env для полного шаблона.

Tools

Discovery

Инструмент	Назначение
list_datasets	Перечислить все лог-датасеты
get_dataset_schema	Названия столбцов и их типы
get_dataset_info	Метаданные (created_at, retention, time window)
get_dataset_stats	Количество событий и объём хранилища
sample_events	Последние N событий (ограничено по времени и строкам)

Query

Инструмент	Назначение
query_sql	SQL SELECT по временному окну. DDL/DML заблокированы. Авто-вставка LIMIT.
query_promql	Instant или range-запрос PromQL к набору метрик

Alerts

Инструмент	Назначение
list_alerts	Перечислить все оповещения с состоянием, уровнем важности, тегами
get_alert	Полная конфигурация одного оповещения
list_alert_tags	Все теги оповещений, которые используются
enable_alert	Включить оповещение
disable_alert	Выключить оповещение
evaluate_alert	Принудительно оценить сейчас. Может выдавать реальные уведомления.
create_alert	Создать оповещение через guided Q&A (8 вопросов, перед отправкой подтверждение)

Alert targets

Инструмент	Назначение
list_alert_targets	Перечислить цели (Slack, webhook, Alertmanager)
get_alert_target	Полная конфигурация одной цели
create_alert_target	Создать новую цель Slack / webhook / Alertmanager

Diagnostics

Инструмент	Назначение
ping	Проверить доступность, вернуть версию и статус
explain_query	EXPLAIN SQL-запроса без выполнения

RBAC (read-only)

Инструмент	Назначение
list_users	Перечислить всех пользователей
get_user_roles	Роли для конкретного пользователя
list_roles	Все имена ролей
get_role	Определение привилегий для роли
get_default_role	Роль по умолчанию для новых пользователей

Admin (read-only)

Инструмент	Назначение
get_cluster_status	Все ноды со статусом (распределённый режим)
get_cluster_metrics	Агрегированные метрики ingest / query / storage
get_retention	Политика retention для набора данных

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    # заполните ваши значения

# Сборка
npm run build           # только сервер (tsc)
npm run build:ui        # только UI на React (vite)
npm run build:all       # и то, и другое

# Запуск
node dist/server.js         # режим stdio
node dist/server.js http    # HTTP-режим (порт 8787)

# Разработка
npm run dev             # tsc --watch
npm run dev:ui          # dev-сервер vite (проксирует API на :8787)
npm test
npm run lint
npm run fix             # автоисправления биомы

CI (GitHub Actions) запускает lint + build:all + тесты на каждый push/PR в ветку main на Node 22. При слиянии в main Docker-образ публикуется в ghcr.io/parseablehq/parseable-mcp-server.

Security

API-key Parseable живут в конфигурации MCP-клиента. Используйте ключи с минимально необходимыми правами.
HTTP-клиенты передают учетные данные в X-Parseable-URL и X-API-Key; всегда используйте HTTPS для удалённых развёртываний.
query_sql блокирует DDL/DML и принудительно накладывает LIMIT на строки. Временной оконной диапазон обязателен.
evaluate_alert может отправлять реальные уведомления — внимательно проверьте вызов перед подтверждением.
Телеметрия отсутствует. Исходящие вызовы идут только к Parseable-инстансу, указанному пользователем.

License

Apache-2.0. См. LICENSE.