# How to Set Up the ClickHouse MCP Server for AI Agents Running analytical queries with AI agents requires strict safety controls to prevent performance issues. This guide covers how to set up the official ClickHouse MCP server using uv, configure secure read-only permissions, and integrate the server with Cursor, Claude Desktop, and Fast.io Coordination Rooms. Source: https://fast.io/resources/clickhouse-mcp-server-setup/ Last reviewed: 2026-08-23 ## Why Security Configuration Matters for ClickHouse MCP Connections An AI agent tasked with analyzing a database can easily execute a massive, un-indexed cross-join over millions of rows, bringing production query systems to a standstill. The underlying challenge is not that the model lacks reasoning capabilities, but rather that standard database connections lack context-aware guards for automated queries. Setting up a dedicated Model Context Protocol server for ClickHouse provides a direct, secure bridge for AI clients to run analytical queries under strict controls. The Model Context Protocol (MCP) functions as an open standard enabling models to safely interact with external systems. By deploying the official `mcp-clickhouse` server, you can allow AI agents to execute SQL queries, list tables, and inspect schemas directly within a secure, controlled workspace. This setup enables models like Claude to query large analytical databases while maintaining complete visibility and control over what the assistant is allowed to execute. Instead of exposing raw database credentials or using administrative roles, teams can enforce structural safety at the database and server configuration levels. When agents query structured data in ClickHouse, they run only optimized analytical statements that are bounded by session timeouts, user quotas, and read-only constraints. Fast.io provides [shared workspaces](/product/workspaces/) that act as neutral ground for these operations, ensuring that database access is strictly managed. Note that not every MCP server installs like this one. Fastio's is remote and hosted, so it needs a URL rather than a local install, as the [Fastio MCP integration guide](/resources/fastio-mcp-server-integration-developers/) sets out. ## How to Install the ClickHouse MCP Server via Python and UV Setting up the integration begins with installing the runtime dependencies. The official ClickHouse MCP server runs as a Python process communicating over standard inputs and outputs (stdio). To manage the server without cluttering your system's global Python environment, you can use the `uv` package manager, which manages virtual environments and dependencies. Before starting the setup, confirm you have `uv` and Python installed on your local machine. You will also need the connection details for your ClickHouse service. If you are using ClickHouse Cloud, the hostname, port, username, and password can be retrieved from your service console. To check if `uv` is available, run the following command in your terminal: ```bash which uv ``` If the command returns a valid path, you can run the MCP server directly using the `uv run` command. The command downloads and executes the `mcp-clickhouse` package in a clean environment: ```bash uv run --with mcp-clickhouse --python 3.10 mcp-clickhouse ``` Using `uv run` ensures that the latest version of the MCP server is retrieved and run with the correct Python version. If your local environment restricts downloading packages on the fly, you can alternatively install the server globally using standard package managers: ```bash pip install mcp-clickhouse ``` Once installed, you can launch the server using Python's module syntax: ```bash python3 -m mcp_clickhouse.main ``` Using the `uv` toolchain is the recommended path for development and local testing because it avoids path conflicts and manages package updates automatically. ## Configuring Environment Variables for Database Security Connecting the MCP server to ClickHouse requires specifying the connection details and security parameters. The server reads these configurations from environment variables. Because AI agents should never have permission to drop tables or modify database schemas on a production system, ClickHouse enforces read-only safety checks by default. When defining connection details, you must specify the target host, port, credentials, and whether to use a secure TLS connection. For standard ClickHouse Cloud deployments, the service uses HTTPS on port `8443`. If you are connecting to a self-managed instance that uses plain HTTP, you can set the port to `8123` and disable secure transport. The list below contains the connection variables and their purposes: * **`CLICKHOUSE_HOST`**: The hostname of your ClickHouse service. * **`CLICKHOUSE_PORT`**: The connection port, which defaults to `8443` for secure TLS. * **`CLICKHOUSE_USER`**: The database user account configured for the agent. * **`CLICKHOUSE_PASSWORD`**: The password associated with the user account. * **`CLICKHOUSE_SECURE`**: Set to `true` to enable TLS/SSL encryption, or `false` for plain text connections. To prevent agents from modifying data or executing destructive commands, the MCP server provides specific security switches: * **`CLICKHOUSE_ALLOW_WRITE_ACCESS`**: Set to `true` if you explicitly want the agent to execute write commands (DML/DDL) like `INSERT`, `CREATE`, or `ALTER`. By default, this is disabled. * **`CLICKHOUSE_ALLOW_DROP`**: Set to `true` if the agent is allowed to run `DROP` or `TRUNCATE` commands. This requires write access to be enabled first. Restricting the agent to read-only credentials configuration for safety protects the database while still enabling schema exploration across millions of rows of analytical data. The model can inspect table layouts, view row counts, and execute read-only SQL queries to extract aggregate insights. This balance lets your team use AI for complex analytics without exposing raw database tables to accidental deletion. ## Steps to Connect the ClickHouse MCP Server to IDEs and Chat Clients Once you have defined your environment variables and verified your connection credentials, you must configure your AI client to launch the MCP server. Major development tools like Cursor, Windsurf, Claude Code, and Claude Desktop support standard stdio MCP servers. To connect ClickHouse to Claude Desktop, you must modify the client's configuration file. On macOS, this file is located at `~/Library/Application Support/Claude/claude_desktop_config.json`. On Windows, the file is located at `%APPDATA%/Claude/claude_desktop_config.json`. Open the file in a text editor and add the `mcp-clickhouse` server under the `mcpServers` object: ```json { "mcpServers": { "mcp-clickhouse": { "command": "uv", "args": [ "run", "--with", "mcp-clickhouse", "--python", "3.10", "mcp-clickhouse" ], "env": { "CLICKHOUSE_HOST": "your-clickhouse-host", "CLICKHOUSE_USER": "your-clickhouse-user", "CLICKHOUSE_PASSWORD": "your-clickhouse-password" } } } } ``` After saving the configuration, restart Claude Desktop to apply the changes. The chat composer will display a connector icon indicating that the ClickHouse tools are active. If your team is evaluating different options for hosting these workflows, you can review the details on the [Fast.io pricing page](/pricing/). For Cursor, you can configure the server globally or locally within a project by creating a `.cursor/mcp.json` file in the root directory. Add the same JSON block to enable the server for the workspace. If you are using Claude Code, you can register the server directly from the terminal by running: ```bash claude mcp add --transport stdio --env CLICKHOUSE_HOST=your-clickhouse-host --env CLICKHOUSE_USER=your-clickhouse-user --env CLICKHOUSE_PASSWORD=your-clickhouse-password --scope user mcp-clickhouse -- uv run --with mcp-clickhouse --python 3.10 mcp-clickhouse ``` To verify that the connection is active, prompt the agent: ```text List the databases available in ClickHouse, then show me the tables in one of them. ``` The agent will query the MCP server, list the schemas, and display the tables. If the query fails, check the system console or logs to verify that the `uv` path is resolved correctly and that the database host is reachable from your local network. ## Managing Analytical Workflows in Fast.io Coordination Rooms Setting up the ClickHouse MCP server on a developer's machine allows that individual to query databases via chat. However, in team environments where multiple agents and people coordinate, local setups quickly become siloed. When an agent runs queries and writes analytical reports, that work is often stranded on a single machine or hidden within a private chat history. Fast.io provides the neutral ground where team members and AI agents collaborate in shared, organization-owned workspaces. Instead of managing file sync using consumer tools that lack agent permissions, teams can use [Fast.io Coordination Rooms](/product/rooms/) to orchestrate workflows between humans and different agent frameworks. For example, a data-analyst agent running queries against the ClickHouse MCP server can export query results to a CSV file in a shared folder. The analyst agent then posts a message in the Coordination Room, notifying the team. A writer agent can automatically detect this file change, run its own tools to read the CSV, and compile a final markdown report in the same workspace. Fast.io exposes this entire intelligence layer through a consolidated MCP toolset. By connecting their agents to the Fast.io MCP endpoint at `https://mcp.fast.io/mcp/key`, teams allow agents to create branded shares, manage folders, and query stored documents using semantic search. This setup turns raw database queries into collaborative team outputs, keeping all stakeholders aligned in real time. ### Starting Collaborative Analysis on Fast.io To begin coordinating your analytical workflows, you can set up a workspace for your team. Every organization starts with a 14-day free trial, which requires a credit card. | Plans are Starter at $29/mo, Business at $99/mo, and Growth at $299/mo. By registering an organization and setting up a shared workspace, you can bridge ClickHouse queries with collaborative storage, providing neutral ground for agents and human teammates to build reports together. ## Frequently asked questions ### How to connect Claude to ClickHouse database? You can connect Claude Desktop to your ClickHouse database by editing your local `claude_desktop_config.json` file. Install the `uv` tool, then add the `mcp-clickhouse` server under the `mcpServers` key. Configure environment variables like `CLICKHOUSE_HOST`, `CLICKHOUSE_USER`, and `CLICKHOUSE_PASSWORD` with your credentials. Restart Claude Desktop, and the app will display ClickHouse tools in the composer interface, allowing Claude to query the database using the Model Context Protocol. ### Is there an MCP server for ClickHouse? Yes, ClickHouse publishes and supports the official open-source `mcp-clickhouse` server on GitHub. The server runs as a Python process that exposes tools like `run_select_query`, `list_databases`, and `list_tables` using the Model Context Protocol. It allows AI assistants to securely connect to any ClickHouse instance, explore table structures, and run queries. ### How do you configure write permissions for ClickHouse MCP? By default, the ClickHouse MCP server operates in a secure, read-only mode to prevent agents from executing destructive commands. To enable write permissions, you must set the environment variable `CLICKHOUSE_ALLOW_WRITE_ACCESS=true` in your client's configuration file. If you also need to allow schema deletions, you must set `CLICKHOUSE_ALLOW_DROP=true` in addition to enabling write access. ## About Fast.io Fast.io provides shared workspaces where people and AI agents work on the same files, with built-in semantic search and citation-backed chat over what they hold. Agents reach it through a remote MCP server at https://mcp.fast.io/mcp, a REST API at https://api.fast.io/current/, and a command line client published on npm as @vividengine/fastio-cli.