Which integrations are available for this server?

Provides tools for executing read-only SELECT and SHOW queries, analyzing query plans, and discovering metadata (databases, tables, columns) on ClickHouse instances.

How do I use mcp-clickhousex?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcp-clickhousex execute query: SELECT name FROM system.tables LIMIT 5" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

mcp-clickhousex

by alyiox

Overview Schema Related Servers Score Discussions

Python

Remote

MCP ClickHouse Tool

Build Status PyPI Version

A read-only Model Context Protocol (MCP) server for ClickHouse that supports metadata discovery, resources, parameterized SELECT queries, SHOW introspection, query analysis, and snapshot mode for large result sets, with profile-based configuration and strict no-DML/DDL enforcement.

Requirements: Python 3.13+, a running ClickHouse instance, and connection details via environment variables or a config file.

Quick start

Set a DSN and run the server with MCP Inspector:

# 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

Related MCP server: io.github.Aguantar/clickhouse-dataops-mcp

Configuration

All settings use the MCP_CLICKHOUSE prefix. Flat environment variables (e.g. MCP_CLICKHOUSE_DSN) are the straightforward way to configure the default profile when you have a single connection. For multiple profiles, the user-scoped config.json file is recommended.

Single connection: Configure via environment variables.

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

Multiple connections: Use the user-scoped config.json file (recommended). Env vars also work via the MCP_CLICKHOUSE_PROFILES_<NAME>_ prefix (e.g. MCP_CLICKHOUSE_PROFILES_WAREHOUSE_DSN).

Unix-like: ~/.config/mcp-clickhousex/config.json
Windows: %USERPROFILE%\.config\mcp-clickhousex\config.json

Example (config.json):

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

Special characters in credentials: If the username or password contains URL-reserved characters, percent-encode them in the DSN:

Character	Encoding
`#`	`%23`
`?`	`%3F`
`/`	`%2F`
`@`	`%40`
`%`	`%25`

For example, username admin@org and password p#ss? become admin%40org:p%23ss%3F in the DSN: http://admin%40org:p%23ss%3F@host:8123/database.

Tools

Tool descriptions match server.py tool docstrings except the [ClickHouse] prefix is omitted here (it remains in MCP-exposed metadata). Parameter text matches each Field(description=…) on the same tool.

Tool	Description	Key params
`list_profiles`	List configured profiles. Each entry includes name and optional description.	—
`get_cluster_properties`	Get cluster properties and execution limits. Returns ClickHouse server version plus enforced limits (max rows, timeouts) for the profile.	`profile` — Profile name; uses default profile when omitted. Src: profiles.
`run_query`	Execute read-only SELECT or WITH … SELECT. One statement; DML, DDL, SET, SYSTEM, and similar are rejected. Returns `{data, row_count}` where `data` is an RFC 4180 CSV string. Pass `snapshot=true` to persist the result to disk and receive `{snapshot_uri, row_count}` instead; fetch the CSV via the snapshot resource URI. Max-rows cap; overflow sets truncated and row_limit. Same SQL validation as analyze_query.	`sql` (required) — Read-only SELECT or WITH … SELECT. One statement; use qualified db.table or database. Driver placeholder syntax for parameters. `parameters` — Named parameters for driver placeholders (e.g. `%(name)s` or `{name:Type}`). `database` — Session default database for unqualified names. Src: databases. `profile` — Profile name; uses default profile when omitted. Src: profiles. `snapshot` — When true, persist the full result as a CSV file and return a resource URI (`chx://snapshots/{id}`) instead of inline data. Use for queries that may exceed the interactive row limit (1 000). Snapshot limits apply (default 10 000 rows, hard ceiling 50 000). Entries expire after 7 days.
`run_show`	Execute SHOW introspection statement. One statement per call; INTO OUTFILE rejected. Interactive row limits apply (default 500, hard ceiling 1 000). Same timeout as run_query.	`sql` (required) — Single SHOW statement (e.g. SHOW DATABASES, SHOW CREATE TABLE). No INTO OUTFILE. `parameters` — Named parameters for driver placeholders (e.g. `%(name)s` or `{name:Type}`). `database` — Session default database for unqualified names. Src: databases. `profile` — Profile name; uses default profile when omitted. Src: profiles.
`analyze_query`	Explain read-only SELECT or WITH … SELECT. Returns plan, pipeline, and/or syntax text. Default types plan and pipeline. Uses query timeout and optional database; no max-rows cap unlike run_query.	`sql` (required) — Read-only SELECT or WITH … SELECT for EXPLAIN. One statement; same validation as run_query. `parameters` — Named parameters for driver placeholders (e.g. `%(name)s` or `{name:Type}`). `database` — Session default database for unqualified names. Src: databases. `profile` — Profile name; uses default profile when omitted. Src: profiles. `types` — EXPLAIN variants: plan (indexes), pipeline, syntax. Default plan and pipeline if omitted.
`list_databases`	List databases. Rows from system.databases visible to the connection.	`profile` — Profile name; uses default profile when omitted. Src: profiles.
`list_tables`	List tables and views in a database. Rows from system.tables: name, engine, primary_key, sorting_key, partition_key, total_rows, total_bytes for query planning.	`database` — Database to list; client default when omitted. Src: databases. `profile` — Profile name; uses default profile when omitted. Src: profiles.
`list_columns`	List columns for a table or view. Rows from system.columns for the resolved database and table.	`table` (required) — Table or view name, or database.table. Src: tables. `database` — Database when table is unqualified; ignored if table contains a dot. Client default when omitted. Src: databases. `profile` — Profile name; uses default profile when omitted. Src: profiles.

Resources

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

Resource descriptions match description=… on @mcp.resource in server.py (same prefix omission as above).

URI	Description
`chx://profiles`	List configured profiles. Each entry includes name and optional description.
`chx://profiles/{profile}/cluster-properties`	Get cluster properties and execution limits. Returns ClickHouse server version plus enforced limits (max rows, timeouts) for the profile. Src: profiles.
`chx://profiles/{profile}/databases`	List databases. Rows from system.databases visible to the connection. Src: profiles.
`chx://profiles/{profile}/databases/{database}/tables`	List tables and views in a database. Rows from system.tables: name, engine, primary_key, sorting_key, partition_key, total_rows, total_bytes for query planning. Src: profiles, dbs.
`chx://profiles/{profile}/databases/{database}/tables/{table}/columns`	List columns for a table or view. Rows from system.columns for the resolved database and table. Src: profiles, dbs, tables.
`chx://snapshots/{id}`	Fetch a query result snapshot by ID. Returns the full result as a CSV string (header row + data rows). Entries expire after 7 days. Src: run_query with snapshot=true.

Security

Read-only SQL only: run_query allows SELECT / WITH … SELECT; run_show allows a single SHOW statement per call. INTO OUTFILE is not allowed on run_show. Interactive queries enforce a tight row cap (default 500, hard ceiling 1 000); for larger extracts use snapshot=true (default 10 000, hard ceiling 50 000). Parameterized queries are supported where the driver allows (%(name)s or {name:Type} syntax). Use environment variables for connection credentials — never commit secrets.

MCP host examples

Snippets for common MCP clients using uvx mcp-clickhousex (no clone required; ensure uv is on your PATH). Replace connection details as needed.

Cursor

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

Codex

[mcp_servers.clickhouse]
command = "uvx"
args = ["mcp-clickhousex"]

[mcp_servers.clickhouse.env]
MCP_CLICKHOUSE_DSN = "http://default:@localhost:8123/default"

OpenCode

{
  "$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"
      }
    }
  }
}

Claude Code

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

Copilot

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

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 uses MCP_TEST_CLICKHOUSE_DSN to locate the ClickHouse instance. If unset, it falls back to http://admin:password123@localhost:8123/default. Set the variable to point tests at a different server without affecting your production MCP_CLICKHOUSE_DSN:

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

Roadmap

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

Contributing

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

License

MIT. See LICENSE.

Install Server

license - permissive license

quality

maintenance

How are these scores calculated?

Maintenance

–Maintainers

–Response time

–Release cycle

–Releases (12mo)

Commit activity

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

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

Tools

Related MCP Servers

mcp-clickhouse
Databases Developer Tools
stiproot
A
license
A
quality
D
maintenance
An MCP server for ClickHouse with enhanced filtering for database and table discovery, supporting LIKE/NOT LIKE patterns and both ClickHouse and chDB tools.
Last updated 2026-01-13
3
Apache 2.0
io.github.Aguantar/clickhouse
Databases Monitoring
Aguantar
A
license
A
quality
D
maintenance
A DataOps-focused MCP server for ClickHouse that provides query optimization advice, pipeline latency analysis, and data quality monitoring, with read-only safety.
Last updated 2026-03-19
8
MIT
db-connect-mcp
Databases Developer Tools
yugui923
A
license
A
quality
A
maintenance
A read-only MCP server for exploratory data analysis across PostgreSQL, MySQL, and ClickHouse databases, providing safe, read-only access with comprehensive analysis capabilities.
Last updated 2026-07-27
10
6
MIT
clickhouse-mcp-server
Databases Developer Tools
reiple
F
license
A
quality
C
maintenance
Read-only MCP server for ClickHouse that allows listing databases and tables, describing schemas, and running SELECT queries.
Last updated 2026-07-07
4

View all related MCP servers

Related MCP Connectors

classquill-mcp
Read-only MCP server for ClassQuill, a tutoring-business-management platform.
Wafergraph MCP
Read-only MCP server for wafergraph.com's semiconductor & AI supply-chain data: 30 tools, no auth.
DataDoe MCP
Hosted Amazon Seller and Vendor MCP server for Claude, ChatGPT, Cursor, Codex, Gemini, Copilot.

View all MCP Connectors

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

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/alyiox/mcp-clickhousex'

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

MCP ClickHouse Tool

Quick start

Configuration

Tools

Resources

Security

MCP host examples

Cursor

Codex

OpenCode

Claude Code

Copilot

Tests

Roadmap

Contributing

License

Maintenance

Resources

Looking for Admin?

Tools

Related MCP Servers

mcp-clickhouse

io.github.Aguantar/clickhouse

db-connect-mcp

clickhouse-mcp-server

Related MCP Connectors

Latest Blog Posts

MCP directory API