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.
- 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
# 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
./altinity-mcp \
--transport http \
--address 0.0.0.0 \
--port 8080 \
--clickhouse-host localhost \
--openapi http
./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
git clone https://github.com/altinity/altinity-mcp.git
cd altinity-mcp
go build -o altinity-mcp ./cmd/altinity-mcp
docker build -t altinity-mcp .
docker run -it altinity-mcp --clickhouse-host host.docker.internal
git checkout https://github.com/Altinity/altinity-mcp
cd altinity-mcp
helm install altinity-mcp ./helm/altinity-mcp \
--set config.clickhouse.host=clickhouse.example.com \
--set config.clickhouse.database=default \
--set config.limit=5000
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
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
Lists all tables in a ClickHouse database with detailed information.
Parameters:
database
(optional): The database to list tables from
Describes the schema of a specific table including column types, constraints, and metadata.
Parameters:
database
(required): The database nametable_name
(required): The table name
Executes SQL queries against ClickHouse with optional result limiting.
Parameters:
query
(required): The SQL query to executelimit
(optional): Maximum number of rows to return (default: server configured limit, max: 10,000)
Provides complete schema information for the ClickHouse database in JSON format.
Provides detailed information about a specific table including schema, sample data, and statistics.
Helps build efficient ClickHouse SQL queries with context about available tables and best practices.
Arguments:
database
(required): Name of the databasetable_name
(optional): Specific table to focus onquery_type
(optional): Type of query (SELECT, INSERT, etc.)
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.
- With JWE: Add the JWE token to either:
- Path parameter:
/{jwe_token}/openapi/...
(now required) - Authorization header:
Bearer {token}
(alternative) x-altinity-mcp-key
header (alternative)
- Path parameter:
- Without JWE: Use server-configured credentials (no auth needed in requests)
Path: /openapi/list_tables
Parameters:
jwe_token
(path param): JWE authentication tokendatabase
(query param): Name of database (optional, returns all databases if omitted)
Example OpenAPI Path:
GET /{jwe_token}/openapi/list_tables?database={db_name}
Path: /openapi/describe_table
Parameters:
jwe_token
(path param): JWE authentication tokendatabase
(query param): Name of database (required)table_name
(query param): Name of table to describe (required)
Example OpenAPI Path:
GET /{jwe_token}/openapi/describe_table?database={db_name}&table_name={table_name}
Path: /openapi/execute_query
Parameters:
jwe_token
(path param): JWE authentication tokenquery
(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
{
"openapi": "3.1.0",
"info": {
"title": "ClickHouse SQL Interface",
"version": "1.0.0"
},
"servers": [
{"url": "https://your-server:8080/{token}"}
],
"paths": {
"/{jwe_token}/openapi/list_tables": {
"get": {
"operationId": "list_tables",
"parameters": [
{
"name": "jwe_token",
"in": "path",
"required": true,
"schema": {"type": "string"}
},
{
"name": "database",
"in": "query",
"schema": {"type": "string"}
}
]
}
},
"/{jwe_token}/openapi/describe_table": {
"get": {
"operationId": "describe_table",
"parameters": [
{
"name": "jwe_token",
"in": "path",
"required": true,
"schema": {"type": "string"}
},
{
"name": "database",
"in": "query",
"required": true
},
{
"name": "table_name",
"in": "query",
"required": true
}
]
}
},
"/{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.
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
./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
./altinity-mcp \
--transport https \
--server-tls \
--server-tls-cert-file /path/to/server.crt \
--server-tls-key-file /path/to/server.key
./altinity-mcp test-connection \
--clickhouse-host localhost \
--clickhouse-port 8123 \
--clickhouse-database default
go test ./...
Integration tests use Docker containers and require Docker to be running:
go test -v ./cmd/altinity-mcp/...
- Go 1.21 or later
- Docker (for integration tests)
- ClickHouse server (for development)
go build -o altinity-mcp ./cmd/altinity-mcp
# Unit tests
go test ./pkg/...
# Integration tests (requires Docker)
go test -v ./cmd/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
version: '3.8'
services:
altinity-mcp:
build: .
ports:
- "8080:8080"
environment:
- CLICKHOUSE_HOST=clickhouse
- MCP_TRANSPORT=http
- MCP_PORT=8080
depends_on:
- clickhouse
clickhouse:
image: clickhouse/clickhouse-server:latest
ports:
- "8123:8123"
--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-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
--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
version
: Show version informationtest-connection
: Test ClickHouse connection
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests
- Run the test suite
- Submit a pull request
This project is licensed under the Apache License 2.0. See the LICENSE file for details.
For support and questions:
- GitHub Issues: https://github.com/altinity/altinity-mcp/issues
- Email: [email protected]