How to Configure Gemini CLI ClickHouse MCP Server

Published
Length
3 min read

Luis Felipe Dias

All posts

You set up a gemini cli clickhouse mcp server by linking the local agent to a restricted database account. Next, you point the agent settings file to the local server tool. Many teams start by giving the agent a shared admin account to test fast queries. That broad account lets a prompt read private columns or run heavy table scans across production data. How the gemini cli clickhouse mcp server setup works The setup links two pieces on a developer machine. The terminal agent reads a local se

Your coding agents run with your access.

Claude Code reaches prod with a developer's credentials, and approval prompts get clicked through. hoop.dev checks every query, masks sensitive data, and holds risky changes for a human.

You set up a gemini cli clickhouse mcp server by linking the local agent to a restricted database account. Next, you point the agent settings file to the local server tool. Many teams start by giving the agent a shared admin account to test fast queries. That broad account lets a prompt read private columns or run heavy table scans across production data.

How the gemini cli clickhouse mcp server setup works

The setup links two pieces on a developer machine. The terminal agent reads a local settings file when it starts up. That file tells the agent how to launch the Model Context Protocol server as a child process. The server process holds the database host address, the user name, and the secret key.

When a developer asks a question, the terminal agent picks a database tool from the local server. The server opens a network session to ClickHouse and sends the SQL query. ClickHouse checks the user account and runs the query against the target tables. The server then sends the result rows back into the agent context window.

To keep this workflow safe, you must set up SQL-driven access control inside ClickHouse first. ClickHouse manages users, roles, row policies, settings profiles, and quotas as access entities created with SQL. Turning on this mode takes a storage directory on the server and an admin user with management rights. A user can only grant the permissions that they already hold themselves.

Creating a new agent user requires the user creation permission in ClickHouse. The creation step sets the login method, the allowed client hosts, the default roles, and user settings. You should bind the agent account to specific host addresses so outside machines cannot use it. You should also attach a quota and a settings profile to cap memory and query time.

How column grants work in ClickHouse

Database admins can lock down which fields the agent can read during a session. In ClickHouse, you can grant read rights on specific columns of a table to a user. The user can then run queries that ask for only those allowed columns. If the agent asks for any other column, the database refuses the query right away.

Wildcard queries that ask for all columns at once also fail on restricted tables. ClickHouse refuses a full wildcard read and returns no data unless every single column is allowed. Since version 24.10, admins can also use a trailing asterisk to grant rights by table name prefix. This prefix rule helps teams group safe analytics tables under one clear naming pattern.

ClickHouse Access Management + Kubernetes API Server Access: architecture patterns and best practices

Continue reading? Get the full guide.

Free. No spam. Unsubscribe anytime.

What native setup solves and what it leaves open

Native database roles and column grants stop the agent from reading blocked tables or dropping data. Host limits and quotas also help keep bad queries from taking down the whole cluster. These native rules are a strong first step for any team running local AI tools.

Still, native database rules only check who logs in and which columns they pick. First, the local server config file needs a static user name and key stored on disk. Every developer machine that runs the agent holds a copy of that secret key. If a key leaks, someone has to rotate it across every developer laptop by hand.

Second, allowed columns often hold mixed data that is hard to split by schema alone. A support log table or user table may hold emails, phone numbers, card numbers, or national IDs. If the agent has read rights on that column, every matching row flows into the model prompt. Static column grants cannot rewrite those fields inside query results on the fly.

Third, database logs only show that the shared agent user ran a statement at a certain time. They do not tie each query back to a single human identity without making dozens of accounts. Teams also lack a simple way to pause a single risky query for human approval before execution.

Add runtime guardrails and masking beside ClickHouse

Database grants and network rules control who can reach ClickHouse. Even so, an allowed client or agent can send an alter mutation that deletes rows or read raw personal data. In practice, hoop.dev sits inline in the native TCP protocol beside the server as a sidecar for your ClickHouse. For every production query an agent or human sends, hoop.dev decides whether to pass, mask, block, or escalate it for review.

With hoop.dev ClickHouse support, guardrails refuse banned queries before they run or hold risky calls for approval, and data masking rewrites matched string columns in results in memory. Furthermore, hoop.dev holds SOC 2 Type II and is open source on GitHub.

Frequently asked questions

Why did ClickHouse refuse a wildcard select query from the agent?

ClickHouse blocks wildcard select queries when a user only has read rights on specific columns. Tell the agent to list only the allowed column names in every query it writes.

Where should we store the ClickHouse login key for the local server?

Do not check database keys into git repos or shared team config files. Pass the key through local shell variables or remove local secrets by routing traffic through a central layer.

Can one ClickHouse user grant read rights to another agent account?

A ClickHouse user can only grant permissions that they already hold on their own account. They also need explicit access management rights turned on before they can change user grants.

The query runs. The emails stay hidden.