GreptimeDB MCP Server

What is this?

GreptimeDB MCP Server is a dedicated microservice control plane that lets large language models and autonomous agents query and analyze high-performance time-series data in real time. It packages native GreptimeDB APIs into a standardized MCP protocol, so you can seamlessly integrate powerful analytics primitives without writing custom data plumbing. With this server, developers can build context-aware copilots, anomaly detection systems, and monitoring dashboards that process billions of rows per second with fine-grained permissions.

Under the hood, the server exposes endpoints like query, ingest write, and schema info, mapping MCP resource requests to GreptimeDB SQL or internal API calls. It supports high-throughput gRPC or REST ingestion protocols (Prometheus remote write, OpenTelemetry, JSON), real-time SQL analytics with window functions, and streaming result sets for large datasets. Security is enforced via OIDC, LDAP, or JWT authentication, and role-based access control at database, table, or column level. Whether you’re feeding data to an LLM for next-gen AI applications or powering observability pipelines, GreptimeDB MCP Server plugs right into any MCP-compliant client or orchestrator.

Quick Start

Install the server using npm:

npm install @greptimetech/server-mcp-greptimedb

Then add it to your MCP client configuration:

{
  "mcpServers": {
    "server-mcp-greptimedb": {
      "command": "npx",
      "args": ["-y", "@greptimetech/server-mcp-greptimedb"],
      "env": {
        "API_KEY": "your-api-key-here"
      }
    }
  }
}

Key Features

Feature 1: Real-time ingestion and querying with millions of metrics per second and sub-millisecond latency.

Feature 2: Semantic API for LLMs that exposes time-series columns by human-readable tags to simplify prompt building.

Feature 3: Fine-grained, role-based access control at database, table, and column levels.

Example Usage

Use an MCP client to run a SQL query and get structured results back, for example querying CPU utilization over the last 5 minutes.

// Example code
const result = await client.callTool({
  name: "query",
  arguments: {
    sql: "SELECT device_id, MAX(voltage) AS max_voltage FROM metrics.fleet_readings WHERE timestamp > NOW() - INTERVAL '5 minutes' GROUP BY device_id;",
    stream: false
  }
});

This example runs a windowed SQL query via the MCP protocol and returns the maximum voltage per device over the last five minutes.

Configuration

The server accepts the following environment variables:

API_KEY – JWT secret for authenticating with the GreptimeDB MCP Server.

DEFAULT_DATABASE (optional) – Default database name to use for queries and writes.

Available Tools/Resources

ingest: Write time-series records in batch via MCP.

query: Execute SQL queries (streaming or non-streaming).

schema/info: Fetch database, table, and column metadata.

listTables: List tables in a given database.

Who Should Use This?

This server is perfect for:

Use case 1: AI agents and LLMs that need real-time, semantic context from time-series streams.

Use case 2: Observability pipelines that require dynamic dashboards and alerting based on live metrics.

Use case 3: Financial and IoT platforms needing high-throughput ingestion and analysis with fine-grained security.

Conclusion

GreptimeDB MCP Server makes it easy to bridge AI agents and high-performance time-series databases, delivering low-latency analytics and semantic data access in a single package. Try it today and see how quickly you can power real-time AI-driven insights with minimal setup.

Check out the GitHub repository for more information and to contribute.