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
search_table_semantics	Поиск таблиц по концепции наблюдаемости, ранжированный по совпавшим терминам; ищет по именам таблиц, семантическим опциям и объявлениям сущностей. schema выбирает базу данных для поиска
query_semantic_graph	Запрос к семантическому графу: summary (что он содержит), entities (узлы), relationships (рёбра) за требуемое временное окно
describe_table	Просмотр профиля таблицы: схема, семантические метаданные, последние примеры строк и рекомендации по запросам
explain_query	Анализ планов выполнения SQL- или TQL-запросов (analyze=true для статистики выполнения; добавьте verbose=true вместе с analyze=true для метрик сканирования по партициям и счётчиков отсечения по индексам)
health_check	Проверка статуса подключения к базе данных и версии сервера

search_table_semantics и семантические метаданные в describe_table читают information_schema.table_semantics. Таблица появляется там, когда она имеет опцию greptime.semantic.* или встроенное соглашение выводит для неё объявление сущности; остальные таблицы отсутствуют. Сервер читает список столбцов представления один раз за процесс и выбирает только те столбцы, которые он предоставляет. entity_declarations требует GreptimeDB 1.3; на более ранних версиях он сообщается как отсутствующий столбец, а не как пустой набор объявлений.

Результаты инструментов ограничены бюджетом GREPTIMEDB_MAX_RESULT_BYTES (по умолчанию 1048576, или 1 МиБ). Результат запроса, превышающий бюджет, возвращает меньше строк и сообщает об этом в truncated и truncation_reason; результат, в котором нет строк для отбрасывания, обрезается с уведомлением в конце. Бюджет — это страховка от результата, слишком большого для потребления, поэтому уменьшите его, если ваш MCP-клиент отклоняет результаты до его достижения.

Межбазовые запросы

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

Инструмент	Как обратиться к другой базе данных
execute_sql, query_range, describe_table	Укажите таблицу как schema.table
execute_tql	metric{__schema__="other_db"}, который принимает только =
search_table_semantics	Передайте schema
query_semantic_graph	Уже охватывает весь каталог; область действия не требуется

Подключённая учётная запись должна иметь разрешение на чтение целевой базы данных. Используйте SHOW DATABASES для их перечисления.

query_semantic_graph читает greptime_private.semantic_entities и greptime_private.semantic_relationships, которые требуют GreptimeDB 1.3. При запуске сервер проверяет, что оба представления существуют, содержат столбцы, которые он читает, и доступны для чтения подключённой учётной записью; если это не так, инструмент не предлагается, и причина регистрируется в журнале. Его временное окно является обязательным и полуоткрытым, [start_time, end_time) по observed_at, и строки агрегируются по 60-секундным интервалам наблюдения в этом окне.

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

Инструмент	Описание
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. Для развёртывания, конфигурации сервера, протоколов записи, синтаксиса конвейеров, проектирования схемы и диагностики производительности направьте ассистента к индексу навыков GreptimeDB по адресу https://docs.greptime.com/SKILL.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 writes: DDL/DML plus pipeline and dashboard changes (DANGEROUS, local/test only)
GREPTIMEDB_MAX_RESULT_BYTES=1048576 # Byte budget for a single tool result (1 MiB)

# 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:

# 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-ребinding

По умолчанию защита от DNS-ребinding отключена для совместимости с прокси, шлюзами и сервисами 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
• create_pipeline, delete_pipeline, create_dashboard, delete_dashboard

# Environment variable
GREPTIMEDB_ALLOW_WRITE=true greptimedb-mcp-server

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

При включении шлюз безопасности обходится для execute_sql, и сервер регистрирует предупреждение при запуске. При выключенном режиме записи эти четыре инструмента возвращают ошибку без обращения к серверу; list_pipelines, list_dashboards и dryrun_pipeline доступны только для чтения и остаются доступными.

⚠️ Опасно: Это позволяет 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.

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

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

• ktanaka101/mcp-server-duckdb
• designcomputer/mysql_mcp_server
• mikeskarl/mcp-prompt-templates