GreptimeDB MCP Server

официальный

Предоставляет AI-ассистентам безопасный и структурированный способ исследования и анализа данных в GreptimeDB.

Документация

greptimedb-mcp-server

Сервер Model Context Protocol (MCP) для GreptimeDB — опенсорсной базы данных для наблюдаемости, которая обрабатывает метрики, логи и трассировки в одном движке.

Позволяет AI-ассистентам запрашивать и анализировать GreptimeDB с помощью SQL, TQL (совместимого с PromQL) и RANGE-запросов, со встроенными функциями безопасности, такими как принудительный режим только для чтения и маскирование данных.

Быстрый старт

# Install
pip install greptimedb-mcp-server

# Run (connects to localhost:4002 by default)
greptimedb-mcp-server --host localhost --database public

Для Claude Desktop добавьте это в конфигурацию (~/Library/Application Support/Claude/claude_desktop_config.json на macOS):

{
  "mcpServers": {
    "greptimedb": {
      "command": "greptimedb-mcp-server",
      "args": ["--host", "localhost", "--database", "public"]
    }
  }
}

Возможности

Инструменты

Инструмент	Описание
`execute_sql`	Выполнение SQL-запросов с выбором формата (csv/json/markdown) и ограничениями
`execute_tql`	Выполнение TQL-запросов (совместимых с PromQL) для анализа временных рядов
`query_range`	Выполнение запросов агрегации по временным окнам с синтаксисом RANGE/ALIGN
`describe_table`	Просмотр профиля таблицы: схема, семантические метаданные, последние образцы строк и рекомендации по запросам
`explain_query`	Анализ планов выполнения SQL или TQL запросов (`analyze=true` для статистики времени выполнения; добавьте `verbose=true` вместе с `analyze=true` для метрик сканирования по партициям и счётчиков отсечения индексов)
`health_check`	Проверка состояния подключения к базе данных и версии сервера

Управление пайплайнами

Инструмент	Описание
`list_pipelines`	Список всех пайплайнов или получение информации о конкретном пайплайне
`create_pipeline`	Создание нового пайплайна с конфигурацией в YAML
`dryrun_pipeline`	Тестирование пайплайна на образцах данных без записи в базу данных
`delete_pipeline`	Удаление конкретной версии пайплайна

Управление дашбордами

Инструмент	Описание
`list_dashboards`	Список всех определений дашбордов Perses
`create_dashboard`	Создание или обновление определения дашборда Perses
`delete_dashboard`	Удаление определения дашборда

Ресурсы и подсказки

Ресурсы: Просмотр таблиц через URI greptime://<table>/data
Подсказки: Встроенные шаблоны Jinja для типовых задач — pipeline_creator, log_pipeline, metrics_analysis, promql_analysis, trace_analysis, table_operation, schema_design_advisor, observability_correlation, ingestion_troubleshooting, query_performance_tuning

По вопросам интеграции с LLM и использования подсказок см. docs/llm-instructions.md.

Конфигурация

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

GREPTIMEDB_HOST=localhost      # Database host
GREPTIMEDB_PORT=4002           # MySQL protocol port (default: 4002)
GREPTIMEDB_USER=root           # Database user
GREPTIMEDB_PASSWORD=           # Database password
GREPTIMEDB_DATABASE=public     # Database name
GREPTIMEDB_TIMEZONE=UTC        # Session timezone

# Optional
GREPTIMEDB_HTTP_PORT=4000      # HTTP API port for pipeline/dashboard management
GREPTIMEDB_HTTP_PROTOCOL=http  # HTTP protocol (http/https)
GREPTIMEDB_POOL_SIZE=5         # Connection pool size
GREPTIMEDB_MASK_ENABLED=true   # Enable sensitive data masking
GREPTIMEDB_MASK_PATTERNS=      # Additional patterns (comma-separated)
GREPTIMEDB_AUDIT_ENABLED=true  # Enable audit logging
GREPTIMEDB_ALLOW_WRITE=false   # Allow write/DDL via execute_sql (DANGEROUS, local/test only)

# Transport (for HTTP server mode)
GREPTIMEDB_TRANSPORT=stdio     # stdio, sse, or streamable-http
GREPTIMEDB_LISTEN_HOST=0.0.0.0 # HTTP server bind host
GREPTIMEDB_LISTEN_PORT=8080    # HTTP server bind port
GREPTIMEDB_ALLOWED_HOSTS=      # DNS rebinding protection (comma-separated)
GREPTIMEDB_ALLOWED_ORIGINS=    # CORS allowed origins (comma-separated)

Аргументы командной строки

greptimedb-mcp-server \
  --host localhost \
  --port 4002 \
  --database public \
  --user root \
  --password "" \
  --timezone UTC \
  --pool-size 5 \
  --mask-enabled true \
  --allow-write false \
  --transport stdio

Режим HTTP-сервера

Для контейнеризованных развертываний или Kubernetes. Требуется mcp>=1.8.0:

# Streamable HTTP (recommended for production)
greptimedb-mcp-server --transport streamable-http --listen-port 8080

# SSE mode (legacy)
greptimedb-mcp-server --transport sse --listen-port 3000

Защита от DNS Rebinding

По умолчанию защита от DNS Rebinding отключена для совместимости с прокси, шлюзами и сервисами Kubernetes. Чтобы включить её, используйте --allowed-hosts:

# Enable DNS rebinding protection with allowed hosts
greptimedb-mcp-server --transport streamable-http \
  --allowed-hosts "localhost:*,127.0.0.1:*,my-service.namespace:*"

# With custom allowed origins for CORS
greptimedb-mcp-server --transport streamable-http \
  --allowed-hosts "my-service.namespace:*" \
  --allowed-origins "http://localhost:*,https://my-app.example.com"

# Or via environment variables
GREPTIMEDB_ALLOWED_HOSTS="localhost:*,my-service.namespace:*" \
GREPTIMEDB_ALLOWED_ORIGINS="http://localhost:*" \
  greptimedb-mcp-server --transport streamable-http

Если вы столкнулись с ошибками 421 Invalid Host Header, либо отключите защиту (по умолчанию), либо добавьте ваш хост в список разрешённых.

Безопасность

Пользователь базы данных только для чтения (рекомендуется)

Создайте пользователя только для чтения в GreptimeDB, используя статический провайдер пользователей:

mcp_readonly:readonly=your_secure_password

Шлюз безопасности на уровне приложения

Все запросы проходят через шлюз безопасности, который:

Блокирует: DROP, DELETE, TRUNCATE, UPDATE, INSERT, ALTER, CREATE, GRANT, REVOKE, EXEC, LOAD, COPY
Блокирует: Закодированные попытки обхода (hex, UNHEX, CHAR)
Разрешает: SELECT, SHOW, DESCRIBE, TQL, EXPLAIN, UNION

Режим записи (отключён по умолчанию)

Сервер по умолчанию работает только для чтения. Для локальной разработки или тестирования вы можете разрешить запись/деструктивные SQL-операторы (DDL/DML, такие как CREATE, DROP, ALTER, INSERT, UPDATE, DELETE) через инструмент execute_sql, включив режим записи:

# Environment variable
GREPTIMEDB_ALLOW_WRITE=true greptimedb-mcp-server

# Or CLI argument
greptimedb-mcp-server --allow-write true

При включении шлюз безопасности обходится для execute_sql, и сервер выводит предупреждение при запуске.

⚠️ Опасность: Это позволяет AI-ассистенту выполнять деструктивные операторы против вашей базы данных. Никогда не включайте это для производственных данных. Если вам нужен только доступ на чтение, используйте пользователя базы данных только для чтения.

Маскирование данных

Конфиденциальные столбцы автоматически маскируются (******) на основе шаблонов имён столбцов:

Аутентификация: password, secret, token, api_key, credential
Финансовые: credit_card, cvv, bank_account
Персональные: ssn, id_card, passport

Настройте с помощью --mask-patterns phone,email, чтобы добавить пользовательские шаблоны.

Журналирование аудита

Все вызовы инструментов журналируются:

2025-12-10 10:30:45 - greptimedb_mcp_server.audit - INFO - [AUDIT] execute_sql | query="SELECT * FROM cpu LIMIT 10" | success=True | duration_ms=45.2

Отключите с помощью --audit-enabled false.

Разработка

# Clone and setup
git clone https://github.com/GreptimeTeam/greptimedb-mcp-server.git
cd greptimedb-mcp-server
uv venv && source .venv/bin/activate
uv sync

# Run tests
pytest

# Format & lint
uv run black .
uv run flake8 src

# Debug with MCP Inspector
npx @modelcontextprotocol/inspector uv --directory . run -m greptimedb_mcp_server.server

Лицензия

Лицензия MIT — см. LICENSE.md.

Благодарности

Вдохновлено: