Altinity Mcp

Altinity MCP 服务

一个模型上下文协议（MCP）服务，提供用于与 ClickHouse® 数据库交互的工具。此服务让 AI 助手和其他 MCP 客户端能够通过标准化协议查询、分析和操作 ClickHouse® 数据库。

功能

• 多种传输选项：支持 STDIO、HTTP 和服务器发送事件（SSE）传输
• 无状态 MCP 协议：HTTP 传输提供无状态 MCP 协议（规范修订版 2026-07-28）——无需会话亲和性，可安全地部署在轮询负载均衡器后；较旧的客户端会自动协商降级至 2025-11-25 及更早版本
• OAuth 2.0 授权：代理 MCP 客户端向任意 OIDC 提供商发起的 OAuth 流程；自动检测 ClickHouse 的 Bearer 或 Basic 身份验证方式（参见 OAuth 2.0 文档）
• JWE 身份验证：可选的基于 JWE 的身份验证，并通过加密安全访问数据库
• TLS 支持：全面支持 ClickHouse® 连接和 MCP 服务端点的 TLS 加密
• 全面的工具：内置用于列出表、描述架构和执行查询的工具
• 动态工具：自动根据 ClickHouse® 视图和表生成 MCP 工具（参见工具文档）
• 资源模板：动态发现数据库架构和表信息
• 查询提示词：用于辅助 AI 构建和优化查询的提示词
• 配置管理：可通过文件、环境变量或 CLI 标志灵活配置
• 热重载：无需重启服务即可动态重新加载配置

目录

• 快速开始
• 集成指南
• 安装与部署
• 配置
• 可用工具
• 可用资源
• 可用提示词
• OpenAI GPTs 集成
• OAuth 2.0 授权
• JWE 身份验证
• TLS 配置
• 开发与测试
• CLI 参考
• 贡献
• 许可证
• 支持

快速开始

使用 STDIO 传输（默认）

# 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

使用 HTTP 传输和 OpenAPI

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

使用 SSE 传输、JWE 身份验证和 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

集成指南

如需了解将 Altinity MCP 集成到各种 AI 工具和平台的详细说明，请参阅我们的集成指南。

安装与部署

使用 Docker

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

使用 Helm 在 Kubernetes 上部署

从 OCI Helm 仓库安装（推荐）

# 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

从本地 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

使用按标签发布的 GHCR 镜像

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

有关 Helm chart 配置选项的详细信息，请参阅 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"

使用已安装的 golang

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

配置

配置文件

创建 YAML 或 JSON 配置文件：

# 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"

设置 connect_host 后，对于 ClickHouse HTTP 连接，它的优先级高于 HTTP_PROXY 和 HTTPS_PROXY，因此配置的地址始终是 TCP 目标地址。当 connect_host 为空时， 环境代理行为保持不变。

注意：有关动态工具配置的详细信息，请参阅工具文档。

使用配置文件：

./altinity-mcp --config config.yaml

环境变量

pkg/config/config.go 中带有 flag: 标签的每个配置字段都可以通过 CLI flag 或环境变量设置。CLI flag 和环境变量名称列在字段的 flag: 和 env: 标签中。运行 altinity-mcp --help 可查看完整列表。

常见示例：

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

不遵循此模式的特殊 flag：--config（配置文件路径）、--config-reload-time、--openapi（一个 flag → 两个结构体字段）。请参阅 altinity-mcp --help。

Prometheus 指标

HTTP 和 SSE 传输（包括 JWE 和多集群模式）会在 server.metrics.enabled、MCP_METRICS_ENABLED 或 --metrics-enabled 为 true 时提供 /metrics。 默认情况下，指标处于禁用状态；禁用时，服务不会执行任何操作：不注册 /metrics 路由、不添加请求中间件、不进行查询检测，也不注册任何收集器。

server.metrics.enabled 仅支持重启后生效。如果配置重载更改了该值，系统会记录警告并保留当前运行值，因为路由和中间件在 HTTP 服务启动时绑定。

此端点提供标准的 Go 运行时和进程收集器，以及以下指标：

指标	类型	标签	含义
altinity_mcp_http_requests_total	counter	route、method、status	按已注册路由模式、规范化方法（GET、POST，……、other）和状态类别（2xx、4xx，……）统计请求数
altinity_mcp_http_request_duration_seconds	histogram	route	处理程序端到端延迟
altinity_mcp_clickhouse_queries_total	counter	kind、outcome	按 select/execute 和 ok/error 统计 ClickHouse 查询数
altinity_mcp_clickhouse_query_duration_seconds	histogram	kind	ClickHouse 往返延迟
altinity_mcp_clickhouse_query_rows	histogram	kind	成功查询返回的行数
altinity_mcp_clickhouse_query_bytes	histogram	kind	成功查询返回的大致字节数
altinity_mcp_blocked_clause_rejections_total	counter	clause	被 blocked_query_clauses 拒绝的查询数
altinity_mcp_clickhouse_up	gauge		根据最近一次 /health 就绪性 ping 得出的 1/0；在没有静态凭据的 JWE/OAuth 模式下为 NaN
altinity_mcp_catalog_cache_*	gauge/counter		多集群目录缓存活动情况（仅限多集群模式）

每个标签都取自固定集合：路由标签使用已注册的模式，而不是原始 URL（因此不会出现 JWE 令牌）；标准集合之外的方法统一归为 other；状态码归为其所属类别。

/metrics 端点无需身份验证。请像限制 /health 的网络访问一样限制对该端点的网络访问。

Helm chart 使用 metrics.enabled 启用此端点。还需设置 metrics.serviceMonitor.enabled，以创建一个抓取现有 HTTP 服务端口的 Prometheus Operator ServiceMonitor。当 config.server.tls.enabled 为 true 时，ServiceMonitor 会自动通过 https 抓取；如果 Prometheus 不信任服务证书，请提供 metrics.serviceMonitor.tlsConfig。

可用工具

execute_query

在 ClickHouse® 上执行 SQL 查询，并可选择限制结果数量。

MCP 工具安全注释：

• 当服务以 --read-only 运行时，execute_query 会以只读工具的形式公开。
• 否则，execute_query 会标记为可能具有破坏性。

参数：

• query（必需）：要执行的 SQL 查询
• limit（可选）：返回的最大行数（默认值：服务配置的限制；最大值：10,000）

动态工具

从 ClickHouse 视图生成的动态工具始终以只读 MCP 工具的形式公开，并附带明确的安全提示。

视图 COMMENT 支持以下任一形式：

• 纯字符串描述。
• 顶层包含 title、description 和 annotations 的严格 JSON 对象。

示例和支持的元数据请参阅工具文档。

可用资源

clickhouse://schema

以 JSON 格式提供 ClickHouse® 数据库的完整架构信息。

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

提供特定表的详细信息，包括架构、示例数据和统计信息。

可用提示词

目前没有可用提示词

OpenAI GPTs 集成

Altinity MCP Server 通过兼容 OpenAPI 的端点，支持与 OpenAI GPTs 无缝集成。这些端点使 GPT 助手能够直接执行 ClickHouse® 数据库操作。

OpenAI MCP/工具参考：

• Apps SDK 参考
• 定义工具
• 构建 MCP 服务
• MCP 概念 / 服务文档

身份验证

• 使用 JWE：将 JWE 令牌添加到以下任一位置：
  1. 路径参数：/{jwe_token}/openapi/...
  2. Authorization 标头：Bearer {token}（替代方式）
  3. x-altinity-mcp-key 标头（替代方式）
• 使用 OAuth：发送 Authorization: Bearer {token}。
• 同时使用两者：自包含的 JWE 优先；否则使用 OAuth 提供凭据。
• 两者均禁用：使用服务配置的 ClickHouse 凭据。

启用任一模式时，精确的 /openapi 架构路由也需要身份验证。动态 HTTP/SSE 工具和 OpenAPI 架构使用按调用方有效凭据隔离的目录；启用身份验证时，绝不会回退到服务凭据。有效配置发生更改时，目录代次会重置，现有 SSE 客户端需要重新连接。未发生更改的重新加载轮询会保留会话。请参阅动态发现。

可用操作

1. 执行只读 SQL 查询

路径：/openapi/execute_query
参数：

• jwe_token（路径参数）：JWE 身份验证令牌
• query（查询参数）：要执行的只读 SQL 查询（必需）；即使 clickhouse.read_only: false，也始终拒绝写入操作。
• limit（查询参数）：返回的最大行数（可选，默认值为 1000，最大值为 10000）

OpenAPI 路径示例：

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

clickhouse.max_query_length 会限制查询的字节数以及动态工具 JSON 请求体的大小（默认值为 10 MiB；负值表示不限制）。输入超出限制时，会在联系 ClickHouse 前返回 HTTP 413。OpenAPI 不会公开 write_query。

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"}
          }
        ]
      }
    }
  }
}

注意：对于 Altinity Cloud 部署，请使用提供的端点 URL 和组织专用令牌。

身份验证与授权

当令牌包含非空的 host 和 username 声明时，JWE 优先。 完整的 JWE 使用自身的连接字段，不受 OAuth 覆盖。部分 JWE 声明会回退到 OAuth，且无法更改其配置的端点。 无效的加密令牌会被拒绝。

OAuth 2.0 授权

MCP 服务支持 OAuth 2.0/OpenID Connect 身份验证，可将 Bearer 令牌传递给 ClickHouse，也可在本地验证。这使 MCP 客户端能够通过身份提供方（Keycloak、Azure AD、Google、AWS Cognito）进行身份验证，并通过 token_processors 使用基于令牌的 ClickHouse 身份验证。

OAuth 标头、查询设置和角色激活按请求和集群隔离；转发调用方的 Bearer 令牌不会更改已配置的 ClickHouse 标头或后续请求。

如需完整的设置说明、特定提供方指南和 ClickHouse 配置，请参阅 OAuth 2.0 授权文档。

JWE 身份验证

启用 JWE 身份验证后，服务端会要求令牌使用 AES Key Wrap（A256KW）和 AES-GCM（A256GCM）加密。这些令牌包含 ClickHouse® 连接参数：

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

JWE 令牌是自包含的：必须提供 host 和 username。缺少 password 或其值为空时，密码仍为空。服务端点、凭据、请求头、角色和 TLS 设置都不会填充缺失的声明。只有运行所需的协议和查询设置会继承；如果未指定端口，HTTP 默认为 8123，TCP 默认为 9000。 如果旧令牌依赖服务端连接默认值，请重新生成。

令牌中非空的 TLS 文件路径必须位于 server.jwe.tls_material_dir（--jwe-tls-material-dir、MCP_JWE_TLS_MATERIAL_DIR）下。解析符号链接后，路径也必须保留在该运维人员控制的目录内。请参阅 JWE 迁移与 TLS 允许列表指南。

HTTP/SSE /jwe-token-generator 端点默认处于禁用状态。要启用管理令牌签发功能，请设置 server.jwe.token_generator.enabled: true，并注入至少 32 字节的 MCP_JWE_TOKEN_GENERATOR_ADMIN_TOKEN。每个请求都必须在 Authorization: Bearer 令牌中提供该密钥。请将此端点限制在可信的管理网络中，并从公共入口中排除。请参阅 生成器设置与请求限制。

使用提供的实用工具生成令牌。

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

更多详情请参阅 jwe_authentication.md。

TLS 配置

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

服务端 TLS

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

开发与测试

开发工作流、构建命令、测试级别以及可选的 OAuth Docker 端到端流程，详见 docs/development_and_testing.md。

完整的 OAuth 设置和 ClickHouse 专属详情，请参阅 OAuth 2.0 授权文档。

CLI 参考

全局标志

• --config：配置文件路径（YAML 或 JSON）
• --log-level：日志级别（debug/info/warn/error）
• --clickhouse-limit：查询结果的默认上限（默认值：1000）
• --openapi：启用 OpenAPI 端点（disable/http/https）（默认值：disable）

ClickHouse® 标志

• --clickhouse-host：ClickHouse® 服务主机
• --clickhouse-connect-host：仅用于底层 TCP 连接的可选主机名或 IP（CLICKHOUSE_CONNECT_HOST）
• --clickhouse-port：ClickHouse® 服务端口
• --clickhouse-database：数据库名称
• --clickhouse-username：用户名
• --clickhouse-password：密码
• --clickhouse-protocol：协议（http/tcp）
• --read-only：只读模式（禁止非只读 SQL，并避免设置会话变量）
• --clickhouse-max-execution-time：查询超时时间，单位为秒
• --clickhouse-http-headers：ClickHouse 请求的 HTTP 请求头（key=value 键值对）

服务端标志

• --transport：传输类型（stdio/http/sse）
• --address：服务地址
• --port：服务端口
• --allow-jwe-auth：启用 JWE 身份验证
• --jwe-secret-key：用于解密 JWE 令牌的密钥（A256KW 要求密钥为 32 字节）。
• --jwt-secret-key：用于验证 JWT 签名的密钥
• --jwe-tls-material-dir：JWE TLS 文件路径的目录允许列表（为空时禁止使用令牌文件路径）
• --jwe-token-generator：启用管理 JWE 令牌签发功能（默认值为 false；MCP_JWE_TOKEN_GENERATOR_ENABLED）
• --jwe-token-generator-admin-token：至少 32 字节的管理员 bearer 密钥（建议通过注入 MCP_JWE_TOKEN_GENERATOR_ADMIN_TOKEN 密钥来提供）
• --jwe-token-generator-max-expiry-seconds：签发令牌的最长有效期（默认值：86400；MCP_JWE_TOKEN_GENERATOR_MAX_EXPIRY_SECONDS）

命令

• version：显示版本信息
• test-connection：测试 ClickHouse® 连接

贡献

1. Fork 此仓库
2. 创建功能分支
3. 进行更改
4. 添加测试
5. 运行测试套件
6. 提交拉取请求

许可证

本项目采用 Apache License 2.0 许可。详情请参阅 LICENSE 文件。

支持

如需支持或有任何疑问：

• GitHub Issues：https://github.com/altinity/altinity-mcp/issues
• 电子邮件：[email protected]