Skip to main content
Glama
Altinity

Altinity MCP

Official
by Altinity
OverviewSchemaRelated ServersScoreDiscussions
Go
Remote

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

  • OAuth 2.0 Authorization: Forward Bearer tokens to ClickHouse for token-based authentication via OIDC providers (see OAuth 2.0 Documentation)

  • 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

  • Dynamic Tools: Automatically generate MCP tools from ClickHouse® views (see Dynamic Tools Documentation)

  • 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
  dynamic_tools:
    - regexp: "mydb\\..*"
      prefix: "db_"
    - name: "get_user_data"
      regexp: "users\\.user_info_view"

logging:
  level: "info"

Note: For detailed information about dynamic tools configuration, see the Dynamic Tools Documentation.

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.

Available Prompts

No prompts currently available

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,
            "schema": {"type": "string"}
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {"type": "integer"}
          }
        ]
      }
    }
  }
}

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

OAuth 2.0 Authorization

The MCP server supports OAuth 2.0 / OpenID Connect authentication with token forwarding to ClickHouse. This enables MCP clients to authenticate via an Identity Provider (Keycloak, Azure AD, Google, AWS Cognito) and have their Bearer tokens forwarded to ClickHouse for token-based authentication via token_processors.

For full setup instructions, provider-specific guides, and ClickHouse configuration, see the OAuth 2.0 Authorization Documentation.

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:

This server cannot be installed

-
security - not tested
F
license - not found
-
quality - not tested

How are these scores calculated?

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Altinity/altinity-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server