ClickHouse MCP setup: SQL, TLS and read access

Choose a small test table and record one expected row before connecting. Decide which columns may be returned and which database user should read them. This guide proposes a test for your environment; it does not verify your account.

Use the database HTTP endpoint

The official server connects through the ClickHouse HTTP interface. For the TLS example below, use the database hostname and its HTTPS port. Native protocol ports such as 9000 or 9440 do not fit this connection. The MCP process itself starts locally with stdio.

VS Code configuration

Install uv, replace the three YOUR_ values and save this as .vscode/mcp.json. VS Code prompts for the password. The example keeps TLS verification enabled and explicitly disables write access in the MCP server.

{
  "servers": {
    "clickhouse": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse",
        "--python",
        "3.12",
        "mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_HOST": "YOUR_CLICKHOUSE_HOST",
        "CLICKHOUSE_PORT": "8443",
        "CLICKHOUSE_USER": "YOUR_READ_USER",
        "CLICKHOUSE_PASSWORD": "${input:clickhouse-password}",
        "CLICKHOUSE_DATABASE": "YOUR_DATABASE",
        "CLICKHOUSE_SECURE": "true",
        "CLICKHOUSE_VERIFY": "true",
        "CLICKHOUSE_ALLOW_WRITE_ACCESS": "false",
        "CLICKHOUSE_MCP_SERVER_TRANSPORT": "stdio"
      }
    }
  },
  "inputs": [
    {
      "id": "clickhouse-password",
      "type": "promptString",
      "description": "ClickHouse password",
      "password": true
    }
  ]
}

Use a database account whose permissions match the selected tables. The server setting does not remove rights from that account. The read-only guide explains both layers.

Check one bounded query

1. Start the server, inspect its offered tools and confirm the selected database.

2. First request SELECT 1 AS connection_check and expect the value 1. This confirms a query, not table permissions.

3. Read only the prepared columns from the test table with an explicit row limit. Compare the result with your note.

4. Record database, user, query and package version. If the result differs, check filters and the data snapshot before increasing the scope.

Use the database planner to define the first operation. The ClickHouse registry search lists candidates and their sources.

Keep a reproducible result

Record more than a successful connection. Keep the full table name, selected columns, filter, row limit and request time with your test notes. Run the same query in your usual database tool with the same user. Different users may see different data. For tables that change during the test, the data snapshot is also part of the comparison. A short result does not mean the query examined little data. Start with a small test dataset and change only one setting at a time while troubleshooting, so that repeating the known query shows the effect of that change.

Is a successful SELECT 1 enough?

It checks query execution. Read access to your intended table still needs its own test.

Which port belongs in the example?

The HTTPS port of the database service. Confirm it in your service settings; 8443 is the example value.

Does read-only make a query cheap?

No. Limit the data range and row count, and inspect query cost before larger requests.

Should I disable TLS verification after a certificate error?

Check hostname, certificate chain and your service configuration first.

Vendor documentation checked on 2 October 2026. No authenticated account test.

1. ClickHouse: MCP server
   Show retrieval command

   curl -s https://github.com/ClickHouse/mcp-clickhouse
2. ClickHouse: Query permissions
   Show retrieval command

   curl -s https://clickhouse.com/docs/concepts/features/configuration/settings/permissions-for-queries
3. VS Code: MCP configuration
   Show retrieval command

   curl -s https://code.visualstudio.com/docs/agent-customization/mcp-servers

All posts