mcp-clickhousex

A read-onlyModel Context Protocol (MCP)server for ClickHouse that supports metadata discovery, resources, parameterizedSELECTqueries,SHOWintrospection, query analysis, and snapshot mode for large result sets, with profile-based configuration and strict no-DML/DDL enforcement.

# Option 1: Run directly with uvx (no clone needed) export MCP_CLICKHOUSE_DSN="http://default:@localhost:8123/default" npx -y @modelcontextprotocol/inspector uvx mcp-clickhousex

# Option 2: Run from source (clone repo, then) export MCP_CLICKHOUSE_DSN="http://default:@localhost:8123/default" npx -y @modelcontextprotocol/inspector uv run main.py

# Connection DSN (required). export MCP_CLICKHOUSE_DSN="http://user:password@host:8123/database" # Optional description for the default profile (tooling/AI discovery). export MCP_CLICKHOUSE_DESCRIPTION="Primary cluster" # Optional max rows per interactive query (default 500; hard ceiling 1000). export MCP_CLICKHOUSE_QUERY_MAX_ROWS="500" # Optional interactive query timeout in seconds (default 30; hard ceiling 300). export MCP_CLICKHOUSE_QUERY_COMMAND_TIMEOUT_SECONDS="30" # Optional max rows for snapshot queries (default 10000; hard ceiling 50000). export MCP_CLICKHOUSE_SNAPSHOT_MAX_ROWS="10000" # Optional snapshot query timeout in seconds (default 120; hard ceiling 300). export MCP_CLICKHOUSE_SNAPSHOT_COMMAND_TIMEOUT_SECONDS="120"

{ "profiles": { "default": { "dsn": "http://default:@localhost:8123/default", "description": "Primary", "query_max_rows": 500, "query_command_timeout_seconds": 60, "snapshot_max_rows": 10000, "snapshot_command_timeout_seconds": 120 }, "warehouse": { "dsn": "http://user:pass@warehouse:8123/analytics", "description": "Warehouse" } } }

Tool descriptions matchserver.pytool docstrings except the[ClickHouse]prefix is omitted here (it remains in MCP-exposed metadata). Parameter text matches eachField(description=…)on the same tool.

The server exposes the same discovery and metadata as the tools above via URI-addressable resources (profile-first hierarchy). Each resource’sdescriptionmatches the corresponding tool (list_profiles,get_cluster_properties,list_databases,list_tables,list_columns), plusSrc:tags for URI path parameters. All resource content is JSON (application/json) except snapshots which return CSV (text/csv). Use path segmentdefaultfor the default profile or database.

Resource descriptions matchdescription=…on@mcp.resourceinserver.py(same prefix omission as above).

Read-only SQL only:run_queryallowsSELECT/WITH … SELECT;run_showallows a singleSHOWstatement per call.INTO OUTFILEis not allowed onrun_show. Interactive queries enforce a tight row cap (default 500, hard ceiling 1 000); for larger extracts usesnapshot=true(default 10 000, hard ceiling 50 000). Parameterized queries are supported where the driver allows (%(name)sor{name:Type}syntax). Use environment variables for connection credentials — never commit secrets.

Snippets for common MCP clients usinguvx mcp-clickhousex(no clone required; ensureuvis on your PATH). Replace connection details as needed.

{ "mcpServers": { "clickhouse": { "command": "uvx", "args": ["mcp-clickhousex"], "env": { "MCP_CLICKHOUSE_DSN": "http://default:@localhost:8123/default" } } } }

[mcp_servers.clickhouse] command = "uvx" args = ["mcp-clickhousex"] [mcp_servers.clickhouse.env] MCP_CLICKHOUSE_DSN = "http://default:@localhost:8123/default"

{ "$schema": "https://opencode.ai/config.json", "mcp": { "clickhouse": { "type": "local", "enabled": true, "command": ["uvx", "mcp-clickhousex"], "environment": { "MCP_CLICKHOUSE_DSN": "http://default:@localhost:8123/default" } } } }

{ "mcpServers": { "clickhouse": { "command": "uvx", "args": ["mcp-clickhousex"], "env": { "MCP_CLICKHOUSE_DSN": "http://default:@localhost:8123/default" } } } }

{ "inputs": [], "servers": { "clickhouse": { "type": "stdio", "command": "uvx", "args": ["mcp-clickhousex"], "env": { "MCP_CLICKHOUSE_DSN": "http://default:@localhost:8123/default" } } } }

Config file locations:Cursor.cursor/mcp.json, Codex/Copilot/OpenCode vary by client; see your client's MCP docs.

Tests require a running ClickHouse instance. The test suite creates a sample table in the default database, seeds it, and drops it after.

# Run all tests (unit + functional + e2e) uv run pytest tests/ -v

The test harness usesMCP_TEST_CLICKHOUSE_DSNto locate the ClickHouse instance. If unset, it falls back tohttp://admin:password123@localhost:8123/default. Set the variable to point tests at a different server without affecting your productionMCP_CLICKHOUSE_DSN:

export MCP_TEST_CLICKHOUSE_DSN="http://user:pass@testhost:8123/default" uv run pytest tests/ -v

No planned features at this time. Open an issue to suggest improvements.

Open issues or PRs; follow existing style and add tests where appropriate.

Official Airtable MCP server and skills for working with bases, records, workflows, and business operations from AI agents.

MCP Server For Apache Doris, an MPP-based real-time data warehouse.

Official MCP Server from Atlan which enables you to bring the power of metadata to your AI tools

Query Onchain data, like ERC20 tokens, transaction history, smart contract state.

Read and write access to your Baserow tables.

Introspect and query your apps deployed to Convex.

Interact with the data stored in Couchbase clusters using natural language.

Maritime intelligence for tracking vessels, analysing ports, and exploring ship data.