Skip to main content
Glama
GreptimeDB MCP Server

GreptimeDB MCP Server

Official
by GreptimeTeam

greptimedb-mcp-server

PyPI - 버전 빌드 워크플로 MIT 라이센스

GreptimeDB 에 대한 MCP(Model Context Protocol) 서버 구현.

이 서버는 AI 비서에게 데이터베이스를 탐색하고 분석할 수 있는 안전하고 체계적인 방법을 제공합니다. AI 비서는 제어된 인터페이스를 통해 테이블 목록을 작성하고, 데이터를 읽고, SQL 쿼리를 실행하여 책임감 있는 데이터베이스 접근을 보장합니다.

프로젝트 상태

이 프로젝트는 아직 개발 중인 실험적 프로젝트입니다. 데이터 보안 및 개인정보 보호 문제는 아직 구체적으로 해결되지 않았으므로 주의해서 사용하시기 바랍니다.

역량

  • list_resources 사용하여 테이블 나열

  • 테이블 데이터를 읽기 위한 read_resource

  • list_tools 로 도구 나열

  • SQL을 실행하기 위한 call_tool

  • list_prompts 로 프롬프트를 나열합니다

  • get_prompt 사용하여 이름으로 프롬프트를 가져옵니다.

설치

지엑스피1

구성

다음 환경 변수를 설정하세요.

GREPTIMEDB_HOST=localhost    # Database host
GREPTIMEDB_PORT=4002         # Optional: Database MySQL port (defaults to 4002 if not specified)
GREPTIMEDB_USER=root
GREPTIMEDB_PASSWORD=
GREPTIMEDB_DATABASE=public

또는 명령줄 인수를 통해:

  • --host 데이터베이스 호스트(기본적으로 localhost

  • --port 데이터베이스 포트, MySQL 프로토콜 포트여야 함, 기본값은 4002 .

  • --user 데이터베이스 사용자 이름, 기본적으로 비어 있음

  • --password 데이터베이스 비밀번호, 기본적으로 비어 있음

  • --database 데이터베이스 이름, 기본적으로 public .

용법

Claude 데스크톱 통합

Claude Desktop의 구성 파일에서 MCP 서버를 구성합니다.

맥OS

위치: ~/Library/Application Support/Claude/claude_desktop_config.json

윈도우

위치: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "greptimedb": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/greptimedb-mcp-server",
        "run",
        "-m",
        "greptimedb_mcp_server.server"
      ],
      "env": {
        "GREPTIMEDB_HOST": "localhost",
        "GREPTIMEDB_PORT": "4002",
        "GREPTIMEDB_USER": "root",
        "GREPTIMEDB_PASSWORD": "",
        "GREPTIMEDB_DATABASE": "public"
      }
    }
  }
}

특허

MIT 라이센스 - 자세한 내용은 LICENSE.md 파일을 참조하세요.

기여하다

Related MCP server: SQLite MCP Server

필수 조건

  • uv 패키지 관리자를 사용한 Python

  • GreptimeDB 설치

  • MCP 서버 종속성

개발

# Clone the repository
git clone https://github.com/GreptimeTeam/greptimedb-mcp-server.git
cd greptimedb-mcp-server

# Create virtual environment
uv venv
source venv/bin/activate  # or `venv\Scripts\activate` on Windows

# Install development dependencies
uv sync

# Run tests
pytest

디버깅을 위해 MCP Inspector를 사용하세요.

npx @modelcontextprotocol/inspector uv \
  --directory \
  /path/to/greptimedb-mcp-server \
  run \
  -m \
  greptimedb_mcp_server.server

승인

이 라이브러리의 구현은 다음 두 저장소에서 영감을 얻었으며 해당 코드를 통합했습니다. 이에 대해 감사드립니다.

감사해요!

Available Tools

15 tools
create_dashboardC

Create or update a Perses dashboard definition in GreptimeDB.

Inputs: name (required), definition (required). Returns: result

create_pipelineC

Create a new pipeline in GreptimeDB.

Inputs: name (required), pipeline (required). Returns: result

delete_dashboardC

Delete a Perses dashboard definition from GreptimeDB.

Inputs: name (required). Returns: result

delete_pipelineB

Delete a specific version of a pipeline from GreptimeDB.

Inputs: name (required), version (required). Returns: result

describe_tableA

Get a table profile: schema, semantic metadata, sample rows, and guidance.

Use it when deciding how to query an unfamiliar table. When the right table
is not known yet, search_table_semantics first; describing candidates one
by one is slower than querying the data.

The semantic profile says what the table means, not what its data says.
signal_type is metric, log, trace, or event; source and source_version name
the ingestion protocol; pipeline names the schema that shaped the rows;
semantic_options carries signal-specific facts such as metric type and
unit. metadata_quality describes how the metric type was obtained --
`declared` by the protocol or `inferred` from the name -- and says nothing
about telemetry quality. entity_declarations lists the entities the table
contributes to the semantic graph. A null or missing semantic field means
unknown, not the opposite fact.

Inputs: table (required), sample_limit, include_samples, include_semantics. Returns: result

dryrun_pipelineA

Test a pipeline with sample data without writing to the database.

You can test a pipeline in two ways:
- Provide 'pipeline' with inline YAML configuration
- Provide 'pipeline_name' to test a previously saved pipeline

Args:
    pipeline: Pipeline YAML configuration (inline)
    pipeline_name: Name of saved pipeline (mutually exclusive with pipeline)
    data: Test data in JSON/NDJSON format
    data_type: Optional content type (e.g., 'application/x-ndjson')

Inputs: data, pipeline, data_type, pipeline_name. Returns: result

execute_sqlA

Execute SQL query against GreptimeDB. Please use MySQL dialect.

Read-only by default. When the server runs with write mode enabled
(--allow-write / GREPTIMEDB_ALLOW_WRITE), destructive SQL (DDL/DML) is
also permitted.

Inputs: query (required), limit, format. Returns: result

execute_tqlC

Execute TQL query for time-series analysis. TQL is PromQL-compatible - use standard PromQL syntax.

Inputs: end (required), step (required), query (required), start (required), +2 more. Returns: result

explain_queryC

Analyze SQL or TQL query execution plan.

Inputs: query (required), analyze, verbose. Returns: result

health_checkA

Check GreptimeDB connection status and server version.

Inputs: no named parameters. Returns: result

list_dashboardsA

List all Perses dashboard definitions stored in GreptimeDB.

Inputs: no named parameters. Returns: result

list_pipelinesC

List all pipelines or get details of a specific pipeline.

Inputs: name. Returns: result

query_rangeC

Execute time-window aggregation query using GreptimeDB's RANGE query syntax.

Inputs: align (required), table (required), select (required), by, +5 more. Returns: result

query_semantic_graphA

Query the semantic graph: which entities exist and which are related.

Use view=summary when the entity and relationship types in this graph are
not known yet; it reports them with the endpoint type pairs each
relationship connects. With a type or an id already in hand, query
entities or relationships directly.

The window is required and half-open, [start_time, end_time), over
observed_at -- the 60-second bucket an observation was recorded in. Rows
are aggregated across the buckets in the window, and the result echoes the
window and the limit it used.

relationships returns one row per edge per confidence. The database reports
confidence 1.0 for a bucket whose client and server spans paired and 0.5
for one where only the client was seen, and it switches request_count,
error_count and the durations to whichever population that bucket
describes: paired requests timed by the server span, or unmatched clients
timed by their own. An edge observed both ways therefore comes back as two
rows. unmatched_count reports client spans with no paired server span.
Durations are in seconds.

entities returns one row per distinct set of attributes, so an entity whose
descriptive attributes changed inside the window appears more than once;
item_count counts rows, not entities. first_seen and last_seen bound where
the row was observed inside this window, not when the entity first existed.

Ordering is by type and endpoint. Only `calls` edges carry request, error
and duration counts, so pass rel_type=calls to order by error and request
count instead. When complete is false, more rows matched than the limit and
later types may be absent entirely rather than merely cut short.

A missing edge is not evidence that two entities are unrelated: it can also
mean the call was not instrumented, was sampled out, or fell outside this
window. Entities are not deduplicated across identity schemes, so one
process can appear under two ids if two sources named it differently.

entity_id_attrs names the attributes an id was assembled from and
source_tables names the telemetry tables that witnessed it. Identifiers
from alerts and other tools are not graph ids unless a query here returned
that exact string.

When masking is on, a returned field is hidden if its own name matches a
sensitive pattern, and an attribute map is also masked by the names inside
it. entities additionally hides entity_id when a masked attribute helped
build it; relationships cannot do the same, because its view does not carry
attribute names, so such a value can still appear there as src_id or
dst_id.

Inputs: view (required), end_time (required), start_time (required), limit, +9 more. Returns: result

search_table_semanticsA

Find tables by observability concept when the right table name is unknown.

Searches table names, semantic options, and entity declarations, and ranks
tables by how many query terms they matched. Use it before describe_table
when the schema is wide or table names do not say what they hold.

It searches schema metadata only, never telemetry row values, so it can say
which table holds Redis memory usage but not which row belongs to
`Redis02`. It ranks on the values in that metadata, not on the schema's own
key names, so search for `gauge` or `bytes` rather than `metric type`. Once
it returns candidates, query their data or describe one of them; do not
describe every candidate in turn.

It covers only the database this server is connected to, unlike
describe_table, which accepts a schema-qualified name.

Only tables carrying a `greptime.semantic.*` option, or one a built-in
convention derives a declaration for, are visible here. A table absent from
the results may still exist and hold the data, so fall back to SHOW TABLES
rather than concluding it is not there.

Inputs: query (required), limit, signal_type. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 15 tools

    Disambiguation5/5

    Each tool targets a distinct resource and action: health, table/semantic metadata, query execution, pipeline lifecycle, and dashboard lifecycle. Even overlapping tools like search_table_semantics and describe_table are explicitly differentiated in their descriptions.

    Naming Consistency4/5

    Most names follow a consistent verb_noun snake_case pattern such as execute_sql, list_pipelines, and create_dashboard. health_check is a minor outlier since it is a noun compound rather than check_health, but it does not create real confusion.

    Tool Count5/5

    At 15 tools, the server sits at the upper edge of the ideal range but remains well-scoped. Each tool supports a distinct workflow covering health, metadata discovery, multiple query modes, pipeline management, and dashboards.

    Completeness4/5

    The core workflows are well covered: health checks, table discovery, semantic graph queries, SQL/TQL/range querying with explain support, pipeline lifecycle operations, and dashboard CRUD. The main gap is the lack of an explicit pipeline update/edit tool, though create_pipeline and versioned deletion may partially cover this.

    Maintenance

    ActivityActive
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A Model Context Protocol server implementation that enables AI assistants to execute SQL queries and interact with SQLite databases through a structured interface.
      7
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      A Model Context Protocol (MCP) server that provides read-only TDengine database queries for AI assistants, allowing users to execute queries, explore database structures, and investigate data directly from AI-powered tools.
      6
      11
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A Model Context Protocol server that provides AI assistants with comprehensive access to SQL databases, enabling schema inspection, query execution, and database operations with enterprise-grade security.
      62 npm
      9
      MIT