icon for mcp server

Altinity

STDIO

MCP server for ClickHouse database integration with query execution and schema management tools

Altinity MCP Server

Coverage Status

A Model Context Protocol (MCP) server that provides tools for interacting with ClickHouse® databases. This server enables AI assistants and other MCP clients to query, analyze, and interact with ClickHouse® databases through a standardized protocol.

Features

  • Multiple Transport Options: Support for STDIO, HTTP, and Server-Sent Events (SSE) transports
  • JWE Authentication: Optional JWE-based authentication with encryption for secure database access
  • TLS Support: Full TLS encryption support for both ClickHouse® connections and MCP server endpoints
  • Comprehensive Tools: Built-in tools for listing tables, describing schemas, and executing queries
  • Resource Templates: Dynamic resource discovery for database schemas and table information
  • Query Prompts: AI-assisted query building and optimization prompts
  • Configuration Management: Flexible configuration via files, environment variables, or CLI flags
  • Hot Reload: Dynamic configuration reloading without server restart

Table of Contents

Quick Start

Using STDIO Transport (Default)

# Basic usage with default settings
./altinity-mcp --clickhouse-host localhost --clickhouse-port 8123

# With custom database and credentials
./altinity-mcp \
  --clickhouse-host clickhouse.example.com \
  --clickhouse-port 9000 \
  --clickhouse-protocol tcp \
  --clickhouse-database analytics \
  --clickhouse-username reader \
  --clickhouse-password secret123 \
  --clickhouse-limit 5000

Using HTTP Transport with OpenAPI

./altinity-mcp \
  --transport http \
  --address 0.0.0.0 \
  --port 8080 \
  --clickhouse-host localhost \
  --openapi http

Using SSE Transport with JWE Authentication and OpenAPI

./altinity-mcp \
  --transport sse \
  --port 8080 \
  --allow-jwe-auth \
  --jwe-secret-key "your-jwe-encryption-secret" \
  --jwt-secret-key "your-jwt-signing-secret" \
  --clickhouse-host localhost \
  --openapi http

Integration Guide

For detailed instructions on integrating Altinity MCP with various AI tools and platforms, see our Integration Guide.

Installation & Deployment

Using Docker

docker run -it --rm ghcr.io/altinity/altinity-mcp:latest --clickhouse-host clickhouse

Kubernetes with Helm

From OCI helm registry (recommended)

# Install from OCI registry
helm install altinity-mcp oci://ghcr.io/altinity/altinity-mcp/helm/altinity-mcp \
  --set config.clickhouse.host=clickhouse.example.com \
  --set config.clickhouse.database=default \
  --set config.clickhouse.limit=5000

From local helm chart

git clone https://github.com/Altinity/altinity-mcp
cd altinity-mcp
helm install altinity-mcp ./helm/altinity-mcp \
  --set config.clickhouse.host=clickhouse-service \
  --set config.clickhouse.database=analytics \
  --set config.server.transport=http \
  --set config.server.port=8080

For detailed Helm chart configuration options, see Helm Chart README.

Docker Compose

version: '3.8'
services:
  altinity-mcp:
    build: .
    ports:
      - "8080:8080"
    environment:
      - CLICKHOUSE_HOST=clickhouse
      - MCP_TRANSPORT=http
      - MCP_PORT=8080
    depends_on:
      - clickhouse
    entrypoint: ["/bin/sh", "-c", "/bin/altinity-mcp"]
  
  clickhouse:
    image: clickhouse/clickhouse-server:latest
    ports:
      - "8123:8123"

From Source

git clone https://github.com/altinity/altinity-mcp.git
cd altinity-mcp
go build -o altinity-mcp ./cmd/altinity-mcp

Configuration

Configuration File

Create a YAML or JSON configuration file:

# config.yaml
clickhouse:
  host: "localhost"
  port: 8123
  database: "default"
  username: "default"
  password: ""
  protocol: "http"
  read_only: false
  max_execution_time: 600
  tls:
    enabled: false
    ca_cert: ""
    client_cert: ""
    client_key: ""
    insecure_skip_verify: false

server:
  transport: "stdio"
  address: "0.0.0.0"
  port: 8080
  tls:
    enabled: false
    cert_file: ""
    key_file: ""
    ca_cert: ""
  jwt:
    enabled: false
    secret_key: ""
  openapi:
    enabled: false
    tls: false

logging:
  level: "info"

Use the configuration file:

./altinity-mcp --config config.yaml

Environment Variables

All configuration options can be set via environment variables:

export CLICKHOUSE_HOST=localhost
export CLICKHOUSE_PORT=8123
export CLICKHOUSE_DATABASE=analytics
export CLICKHOUSE_LIMIT=5000
export MCP_TRANSPORT=http
export MCP_PORT=8080
export LOG_LEVEL=debug

./altinity-mcp

Available Tools

execute_query

Executes SQL queries against ClickHouse® with optional result limiting.

Parameters:

  • query (required): The SQL query to execute
  • limit (optional): Maximum number of rows to return (default: server configured limit, max: 10,000)

Available Resources

clickhouse://schema

Provides complete schema information for the ClickHouse® database in JSON format.

clickhouse://table/{database}/{table}

Provides detailed information about a specific table including schema, sample data, and statistics.

OpenAI GPTs Integration

The Altinity MCP Server supports seamless integration with OpenAI GPTs through its OpenAPI-compatible endpoints. These endpoints enable GPT assistants to perform ClickHouse® database operations directly.

Authentication

  • With JWE: Add the JWE token to either:
    1. Path parameter: /{jwe_token}/openapi/... (now required)
    2. Authorization header: Bearer {token} (alternative)
    3. x-altinity-mcp-key header (alternative)
  • Without JWE: Use server-configured credentials (no auth needed in requests)

Available Actions

1. Execute SQL Query

Path: /openapi/execute_query
Parameters:

  • jwe_token (path param): JWE authentication token
  • query (query param): SQL query to execute (required)
  • limit (query param): Maximum rows to return (optional, default 1000, max 10000)

Example OpenAPI Path:

GET /{jwe_token}/openapi/execute_query?query=SELECT%20*%20FROM%20table&limit=500

Configuration Example for GPTs

{
  "openapi": "3.1.0",
  "info": {
    "title": "ClickHouse® SQL Interface",
    "version": "1.0.0"
  },
  "servers": [
    {"url": "https://your-server:8080/{token}"}
  ],
  "paths": {
    "/{jwe_token}/openapi/execute_query": {
      "get": {
        "operationId": "execute_query",
        "parameters": [
          {
            "name": "jwe_token",
            "in": "path",
            "required": true,
            "schema": {"type": "string"}
          },
          {
            "name": "query",
            "in": "query",
            "required": true
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {"type": "integer"}
          }
        ]
      }
    }
  }
}

Note: For Altinity Cloud deployments, use the provided endpoint URL with your organization-specific token.

JWE Authentication

When JWE authentication is enabled, the server expects tokens encrypted using AES Key Wrap (A256KW) and AES-GCM (A256GCM). These tokens contain ClickHouse® connection parameters:

{
  "host": "clickhouse.example.com",
  "port": 8123,
  "database": "analytics",
  "username": "user123",
  "password": "secret",
  "protocol": "http",
  "secure": "false"
}

Generate tokens using the provided utility.

go run ./cmd/jwe_auth/jwe_token_generator.go \
  --jwe-secret-key "your-jwe-encryption-secret" \
  --jwt-secret-key "your-jwt-signing-secret" \
  --host "clickhouse.example.com" \
  --port 8123 \
  --database "analytics" \
  --username "user123" \
  --password "password123" \
  --expiry 86400

More details in jwe_authentication.md

TLS Configuration

ClickHouse® TLS

./altinity-mcp \
  --clickhouse-tls \
  --clickhouse-tls-ca-cert /path/to/ca.crt \
  --clickhouse-tls-client-cert /path/to/client.crt \
  --clickhouse-tls-client-key /path/to/client.key

Server TLS

./altinity-mcp \
  --transport https \
  --server-tls \
  --server-tls-cert-file /path/to/server.crt \
  --server-tls-key-file /path/to/server.key

Testing

Test ClickHouse® Connection

./altinity-mcp test-connection \
  --clickhouse-host localhost \
  --clickhouse-port 8123 \
  --clickhouse-database default

Run Tests

go test ./...

Integration Tests

Integration tests use Docker containers and require Docker to be running:

go test -v ./cmd/altinity-mcp/...

Development

Prerequisites

  • Go 1.24 or later
  • Docker (for integration tests)
  • ClickHouse® server (for development)

Building

go build -o altinity-mcp ./cmd/altinity-mcp

Running Tests

# Unit tests
go test ./pkg/...

# Integration tests (requires Docker)
go test -v ./cmd/altinity-mcp/...

CLI Reference

Global Flags

  • --config: Path to configuration file (YAML or JSON)
  • --log-level: Logging level (debug/info/warn/error)
  • --clickhouse-limit: Default limit for query results (default: 1000)
  • --openapi: Enable OpenAPI endpoints (disable/http/https) (default: disable)

ClickHouse® Flags

  • --clickhouse-host: ClickHouse® server host
  • --clickhouse-port: ClickHouse® server port
  • --clickhouse-database: Database name
  • --clickhouse-username: Username
  • --clickhouse-password: Password
  • --clickhouse-protocol: Protocol (http/tcp)
  • --read-only: Read-only mode
  • --clickhouse-max-execution-time: Query timeout in seconds
  • --clickhouse-http-headers: HTTP headers for ClickHouse requests (key=value pairs)

Server Flags

  • --transport: Transport type (stdio/http/sse)
  • --address: Server address
  • --port: Server port
  • --allow-jwe-auth: Enable JWE authentication
  • --jwe-secret-key: Secret key for JWE token decryption (must be 32 bytes for A256KW).
  • --jwt-secret-key: Secret key for JWT signature verification

Commands

  • version: Show version information
  • test-connection: Test ClickHouse® connection

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests
  5. Run the test suite
  6. Submit a pull request

License

This project is licensed under the Apache License 2.0. See the LICENSE file for details.

Support

For support and questions:

Be the First to Experience MCP Now