Power your agent
การติดตั้งจากผู้เผยแพร่ ไม่ใช่เอนด์พอยต์ของ PlugMCP
URL แบบรีโมตหรือคำสั่งบนเครื่องของคุณ? การติดตั้งสองแบบต่างกันอย่างไร
รันบน PlugMCP
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
เปิดจากผู้เผยแพร่
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.
Model Context Protocol server to use ClickHouse® databases in your AI agents
# 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
For detailed instructions on integrating Altinity MCP with various AI tools and platforms, see our Integration Guide.
docker run -it --rm ghcr.io/altinity/altinity-mcp:latest --clickhouse-host clickhouse
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
From a tag-published GHCR image
helm install altinity-mcp oci://ghcr.io/altinity/altinity-mcp/helm/altinity-mcp \
--set image.tag=<tag-or-sha-tag> \
--set config.clickhouse.host=clickhouse.example.com \
--set config.clickhouse.database=default
For detailed Helm chart configuration options, see Helm Chart README.
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"
go install github.com/altinity/altinity-mcp/cmd/altinity-mcp@latest
$(go env GOPATH)/bin/altinity-mcp --help
git clone https://github.com/altinity/altinity-mcp.git
cd altinity-mcp
go build -o altinity-mcp ./cmd/altinity-mcp
Create a YAML or JSON configuration file:
# config.yaml
clickhouse:
host: "localhost"
# Optional TCP destination override. The logical host above remains the
# HTTP Host header and TLS SNI/certificate verification name.
connect_host: ""
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
metrics:
enabled: false
dynamic_tools:
- regexp: "mydb\\..*"
prefix: "db_"
- name: "get_user_data"
regexp: "users\\.user_info_view"
logging:
level: "info"
When connect_host is set, it takes precedence over HTTP_PROXY and
HTTPS_PROXY for ClickHouse HTTP connections so the configured address is
always the TCP destination. Environment proxy behavior is unchanged when
connect_host is empty.
Note: For detailed information about dynamic tools configuration, see the Tools Documentation.
Use the configuration file:
./altinity-mcp --config config.yaml
Every configuration field with a flag: tag in pkg/config/config.go is settable via CLI flag or env var. The CLI flag and env-var name are listed in the field's flag: and env: tags. altinity-mcp --help prints the full surface.
Common examples:
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 MCP_METRICS_ENABLED=true
export LOG_LEVEL=debug
# OAuth — env-var injection lets operators pull secrets from a Kubernetes
# Secret via `valueFrom.secretKeyRef` instead of committing them to YAML.
export MCP_OAUTH_ENABLED=true
export MCP_OAUTH_BROKER=true
export MCP_OAUTH_ISSUER=https://accounts.example.com
export MCP_OAUTH_SIGNING_SECRET=...
./altinity-mcp
Special flags that don't follow this pattern: --config (config file path), --config-reload-time, --openapi (one flag → two struct fields). See altinity-mcp --help.
HTTP and SSE transports (including JWE and multicluster modes) expose
/metrics when server.metrics.enabled, MCP_METRICS_ENABLED, or
--metrics-enabled is true. Metrics are disabled by default, and a disabled
server is a true no-op: no /metrics route, no request middleware, no query
instrumentation, and no collectors registered.
server.metrics.enabled is restart-only. A config reload that changes it
logs a warning and keeps the running value, because the route and middleware
are bound when the HTTP server starts.
The endpoint serves the standard Go runtime and process collectors plus:
Every label is drawn from a fixed set: route labels use registered patterns
rather than raw URLs (so JWE tokens never appear), methods outside the
standard set collapse to other, and status codes collapse to their class.
The /metrics endpoint is unauthenticated. Restrict network access to it in
the same way you would for /health.
The Helm chart uses metrics.enabled for the endpoint. Set
metrics.serviceMonitor.enabled as well to create a Prometheus Operator
ServiceMonitor that scrapes the existing HTTP service port. When
config.server.tls.enabled is true the ServiceMonitor scrapes over https
automatically; supply metrics.serviceMonitor.tlsConfig if Prometheus does
not trust the server certificate.
execute_queryExecutes SQL queries against ClickHouse® with optional result limiting.
MCP tool safety annotations:
--read-only, execute_query is exposed as read-only.execute_query is marked as potentially destructive.Parameters:
query (required): The SQL query to executelimit (optional): Maximum number of rows to return (default: server configured limit, max: 10,000)Dynamic tools generated from ClickHouse views are always exposed as read-only MCP tools with explicit safety hints.
View COMMENT supports either:
title, description, and annotations.See Tools Documentation for examples and supported metadata.
clickhouse://schemaProvides 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.
No prompts currently available
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.
OpenAI MCP/tooling references:
/{jwe_token}/openapi/...Bearer {token} (alternative)x-altinity-mcp-key header (alternative)Authorization: Bearer {token}.The exact /openapi schema route also requires authentication when either mode is enabled. Dynamic HTTP/SSE tools and OpenAPI schemas use catalogs isolated by the caller's effective credential; server credentials are never a fallback under authentication. An effective configuration change resets catalog generations and requires existing SSE clients to reconnect. Unchanged reload polls preserve sessions. See dynamic discovery.
Path: /openapi/execute_query
Parameters:
jwe_token (path param): JWE authentication tokenquery (query param): Read-only SQL query to execute (required); writes are always rejected, even when clickhouse.read_only: false.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
clickhouse.max_query_length bounds the query in bytes and dynamic-tool JSON bodies (default 10 MiB; negative disables the limit). Oversized inputs return HTTP 413 before contacting ClickHouse. OpenAPI does not expose write_query.
{
"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.
JWE takes priority when the token carries nonempty host and username claims.
A complete JWE uses its own connection fields without OAuth overrides. Partial
JWE claims fall through to OAuth and cannot alter its configured endpoint.
Invalid encrypted tokens are rejected.
The MCP server supports OAuth 2.0/OpenID Connect authentication, with Bearer tokens presented to ClickHouse or verified locally. This enables MCP clients to authenticate via an Identity Provider (Keycloak, Azure AD, Google, AWS Cognito) and use token-based ClickHouse authentication via token_processors.
OAuth headers, query settings, and role activation are isolated per request and cluster; forwarding a caller's bearer token does not change the configured ClickHouse headers or later requests.
For full setup instructions, provider-specific guides, and ClickHouse configuration, see the OAuth 2.0 Authorization Documentation.
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"
}
JWE tokens are self-contained: host and username are required. An absent or
empty password remains empty. Server endpoint, credentials, headers, roles,
and TLS settings never fill missing claims. Only operational protocol and query
settings are inherited; an omitted port defaults to 8123 (HTTP) or 9000 (TCP).
Regenerate older tokens that relied on server connection defaults.
Nonempty token TLS file paths require server.jwe.tls_material_dir
(--jwe-tls-material-dir, MCP_JWE_TLS_MATERIAL_DIR). Paths must remain inside
that operator-controlled directory after symlink resolution. See the
JWE migration and TLS allowlist guide.
The HTTP/SSE /jwe-token-generator endpoint is disabled by default. To enable
administrative issuance, set server.jwe.token_generator.enabled: true and
inject MCP_JWE_TOKEN_GENERATOR_ADMIN_TOKEN with at least 32 bytes. Each request
requires that secret as an Authorization: Bearer token. Keep this endpoint on
a trusted administrative network and exclude it from public ingress. See the
generator setup and request limits.
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
Development workflow, build commands, test tiers, and the optional OAuth Docker e2e flow are documented in docs/development_and_testing.md.
For the full OAuth setup and ClickHouse-specific details, see the OAuth 2.0 Authorization Documentation.
--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-connect-host: Optional hostname or IP used only for the underlying TCP connection (CLICKHOUSE_CONNECT_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 (prevents non-read SQL and avoids setting session variables)--clickhouse-max-execution-time: Query timeout in seconds--clickhouse-http-headers: HTTP headers for ClickHouse requests (key=value pairs)--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--jwe-tls-material-dir: Directory allowlist for JWE TLS file paths (empty denies token file paths)--jwe-token-generator: Enable administrative JWE token issuance (default false; MCP_JWE_TOKEN_GENERATOR_ENABLED)--jwe-token-generator-admin-token: Admin bearer secret of at least 32 bytes (prefer MCP_JWE_TOKEN_GENERATOR_ADMIN_TOKEN secret injection)--jwe-token-generator-max-expiry-seconds: Maximum issued token lifetime (default 86400; MCP_JWE_TOKEN_GENERATOR_MAX_EXPIRY_SECONDS)version: Show version informationtest-connection: Test ClickHouse® connectionThis project is licensed under the Apache License 2.0. See the LICENSE file for details.
For support and questions:
Model Context Protocol server to use ClickHouse® databases in your AI agents
เครื่องมือ
ยังไม่มีรายการเครื่องมือ เซิร์ฟเวอร์แบบรีโมตจะได้รายการหลังการตรวจสอบสถานะครั้งแรก
FAQ
คัดลอกคอนฟิก stdio สำหรับ Cursor, Claude Desktop, Claude Code หรือ VS Code ได้ในหน้านี้ คอนฟิกนี้ใช้การติดตั้งของผู้เผยแพร่ ไม่ใช่พร็อกซีของ PlugMCP
ระเบียนนี้ไม่ได้ระบุตัวแปรสภาพแวดล้อมที่จำเป็น
Altinity ทำงานแบบโลคัลผ่าน stdio
ตรวจสอบล่าสุดเมื่อ 2026-11-05 Model Context Protocol server to use ClickHouse® databases in your AI agents
