ClickHouse MCP Server

1# ClickHouse MCP Server
2 
3[![PyPI - Version](https://img.shields.io/pypi/v/mcp-clickhouse)](https://pypi.org/project/mcp-clickhouse)
4 
5An MCP server for ClickHouse.
6 
7<a href="https://glama.ai/mcp/servers/yvjy4csvo1"><img width="380" height="200" src="https://glama.ai/mcp/servers/yvjy4csvo1/badge" alt="mcp-clickhouse MCP server" /></a>
8 
9## Features
10 
11### ClickHouse Tools
12 
13* `run_query`
14  * Execute SQL queries on your ClickHouse cluster.
15  * Input: `query` (string): The SQL query to execute.
16  * Queries run in read-only mode by default (`CLICKHOUSE_ALLOW_WRITE_ACCESS=false`), but writes can be enabled explicitly if needed.
17 
18* `list_databases`
19  * List all databases on your ClickHouse cluster.
20 
21* `list_tables`
22  * List tables in a database with pagination.
23  * Required input: `database` (string).
24  * Optional inputs:
25    * `like` / `not_like` (string): Apply `LIKE` or `NOT LIKE` filters to table names.
26    * `page_token` (string): Token returned by a previous call for fetching the next page.
27    * `page_size` (int, default `50`): Number of tables returned per page.
28    * `include_detailed_columns` (bool, default `true`): When `false`, omits column metadata for lighter responses while keeping the full `create_table_query`.
29  * Response shape:
30    * `tables`: Array of table objects for the current page.
31    * `next_page_token`: Pass this value back to fetch the next page, or `null` when there are no more tables.
32    * `total_tables`: Total count of tables that match the supplied filters.
33 
34### chDB Tools
35 
36* `run_chdb_select_query`
37  * Execute SQL queries using [chDB](https://github.com/chdb-io/chdb)'s embedded ClickHouse engine.
38  * Input: `query` (string): The SQL query to execute.
39  * Query data directly from various sources (files, URLs, databases) without ETL processes.
40 
41### Health Check Endpoint
42 
43When running with HTTP or SSE transport, a health check endpoint is available at `/health`. This endpoint:
44- Returns `200 OK` with the ClickHouse version if the server is healthy and can connect to ClickHouse
45- Returns `503 Service Unavailable` if the server cannot connect to ClickHouse
46 
47Example:
48```bash
49curl http://localhost:8000/health
50# Response: OK - Connected to ClickHouse 24.3.1
51```
52 
53## Security
54 
55### Authentication for HTTP/SSE Transports
56 
57When using HTTP or SSE transport, authentication is **required by default**. The `stdio` transport (default) does not require authentication as it only communicates via standard input/output.
58 
59#### Setting Up Authentication
60 
611. Generate a secure token (can be any random string):
62   ```bash
63   # Using uuidgen (macOS/Linux)
64   uuidgen
65 
66   # Using openssl
67   openssl rand -hex 32
68   ```
69 
702. Configure the server with the token:
71   ```bash
72   export CLICKHOUSE_MCP_AUTH_TOKEN="your-generated-token"
73   ```
74 
753. Configure your MCP client to include the token in requests:
76 
77   For Claude Desktop with HTTP/SSE transport:
78   ```json
79   {
80     "mcpServers": {
81       "mcp-clickhouse": {
82         "url": "http://127.0.0.1:8000",
83         "headers": {
84           "Authorization": "Bearer your-generated-token"
85         }
86       }
87     }
88   }
89   ```
90 
91   For command-line tools:
92   ```bash
93   curl -H "Authorization: Bearer your-generated-token" http://localhost:8000/health
94   ```
95 
96#### Development Mode (Disabling Authentication)
97 
98For local development and testing only, you can disable authentication by setting:
99```bash
100export CLICKHOUSE_MCP_AUTH_DISABLED=true
101```
102 
103**WARNING:** Only use this for local development. Do not disable authentication when the server is exposed to any network.
104 
105## Configuration
106 
107This MCP server supports both ClickHouse and chDB. You can enable either or both depending on your needs.
108 
1091. Open the Claude Desktop configuration file located at:
110   * On macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
111   * On Windows: `%APPDATA%/Claude/claude_desktop_config.json`
112 
1132. Add the following:
114 
115```json
116{
117  "mcpServers": {
118    "mcp-clickhouse": {
119      "command": "uv",
120      "args": [
121        "run",
122        "--with",
123        "mcp-clickhouse",
124        "--python",
125        "3.10",
126        "mcp-clickhouse"
127      ],
128      "env": {
129        "CLICKHOUSE_HOST": "<clickhouse-host>",
130        "CLICKHOUSE_PORT": "<clickhouse-port>",
131        "CLICKHOUSE_USER": "<clickhouse-user>",
132        "CLICKHOUSE_PASSWORD": "<clickhouse-password>",
133        "CLICKHOUSE_ROLE": "<clickhouse-role>",
134        "CLICKHOUSE_SECURE": "true",
135        "CLICKHOUSE_VERIFY": "true",
136        "CLICKHOUSE_CONNECT_TIMEOUT": "30",
137        "CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "30"
138      }
139    }
140  }
141}
142```
143 
144Update the environment variables to point to your own ClickHouse service.
145 
146Or, if you'd like to try it out with the [ClickHouse SQL Playground](https://sql.clickhouse.com/), you can use the following config:
147 
148```json
149{
150  "mcpServers": {
151    "mcp-clickhouse": {
152      "command": "uv",
153      "args": [
154        "run",
155        "--with",
156        "mcp-clickhouse",
157        "--python",
158        "3.10",
159        "mcp-clickhouse"
160      ],
161      "env": {
162        "CLICKHOUSE_HOST": "sql-clickhouse.clickhouse.com",
163        "CLICKHOUSE_PORT": "8443",
164        "CLICKHOUSE_USER": "demo",
165        "CLICKHOUSE_PASSWORD": "",
166        "CLICKHOUSE_SECURE": "true",
167        "CLICKHOUSE_VERIFY": "true",
168        "CLICKHOUSE_CONNECT_TIMEOUT": "30",
169        "CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "30"
170      }
171    }
172  }
173}
174```
175 
176For chDB (embedded ClickHouse engine), add the following configuration:
177 
178```json
179{
180  "mcpServers": {
181    "mcp-clickhouse": {
182      "command": "uv",
183      "args": [
184        "run",
185        "--with",
186        "mcp-clickhouse",
187        "--python",
188        "3.10",
189        "mcp-clickhouse"
190      ],
191      "env": {
192        "CHDB_ENABLED": "true",
193        "CLICKHOUSE_ENABLED": "false",
194        "CHDB_DATA_PATH": "/path/to/chdb/data"
195      }
196    }
197  }
198}
199```
200 
201You can also enable both ClickHouse and chDB simultaneously:
202 
203```json
204{
205  "mcpServers": {
206    "mcp-clickhouse": {
207      "command": "uv",
208      "args": [
209        "run",
210        "--with",
211        "mcp-clickhouse",
212        "--python",
213        "3.10",
214        "mcp-clickhouse"
215      ],
216      "env": {
217        "CLICKHOUSE_HOST": "<clickhouse-host>",
218        "CLICKHOUSE_PORT": "<clickhouse-port>",
219        "CLICKHOUSE_USER": "<clickhouse-user>",
220        "CLICKHOUSE_PASSWORD": "<clickhouse-password>",
221        "CLICKHOUSE_SECURE": "true",
222        "CLICKHOUSE_VERIFY": "true",
223        "CLICKHOUSE_CONNECT_TIMEOUT": "30",
224        "CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "30",
225        "CHDB_ENABLED": "true",
226        "CHDB_DATA_PATH": "/path/to/chdb/data"
227      }
228    }
229  }
230}
231```
232 
2333. Locate the command entry for `uv` and replace it with the absolute path to the `uv` executable. This ensures that the correct version of `uv` is used when starting the server. On a mac, you can find this path using `which uv`.
234 
2354. Restart Claude Desktop to apply the changes.
236 
237### Optional Write Access
238 
239By default, this MCP enforces read-only queries so that accidental mutations cannot happen during exploration. To allow DDL or INSERT/UPDATE statements, set the `CLICKHOUSE_ALLOW_WRITE_ACCESS` environment variable to `true`. The server keeps enforcing read-only mode if the ClickHouse instance itself disallows writes.
240 
241### Destructive Operation Protection
242 
243Even when write access is enabled (`CLICKHOUSE_ALLOW_WRITE_ACCESS=true`), destructive operations (DROP TABLE, DROP DATABASE, DROP VIEW, DROP DICTIONARY, TRUNCATE TABLE) require an additional opt-in flag for safety. This prevents accidental data deletion during AI exploration.
244 
245To enable destructive operations, set both flags:
246```json
247"env": {
248  "CLICKHOUSE_ALLOW_WRITE_ACCESS": "true",
249  "CLICKHOUSE_ALLOW_DROP": "true"
250}
251```
252 
253This two-tier approach ensures that accidental drops are very difficult:
254- **Write operations** (INSERT, UPDATE, CREATE) require `CLICKHOUSE_ALLOW_WRITE_ACCESS=true`
255- **Destructive operations** (DROP, TRUNCATE) additionally require `CLICKHOUSE_ALLOW_DROP=true`
256 
257### Running Without uv (Using System Python)
258 
259If you prefer to use the system Python installation instead of uv, you can install the package from PyPI and run it directly:
260 
2611. Install the package using pip:
262   ```bash
263   python3 -m pip install mcp-clickhouse
264   ```
265 
266   To upgrade to the latest version:
267   ```bash
268   python3 -m pip install --upgrade mcp-clickhouse
269   ```
270 
2712. Update your Claude Desktop configuration to use Python directly:
272 
273```json
274{
275  "mcpServers": {
276    "mcp-clickhouse": {
277      "command": "python3",
278      "args": [
279        "-m",
280        "mcp_clickhouse.main"
281      ],
282      "env": {
283        "CLICKHOUSE_HOST": "<clickhouse-host>",
284        "CLICKHOUSE_PORT": "<clickhouse-port>",
285        "CLICKHOUSE_USER": "<clickhouse-user>",
286        "CLICKHOUSE_PASSWORD": "<clickhouse-password>",
287        "CLICKHOUSE_SECURE": "true",
288        "CLICKHOUSE_VERIFY": "true",
289        "CLICKHOUSE_CONNECT_TIMEOUT": "30",
290        "CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "30"
291      }
292    }
293  }
294}
295```
296 
297Alternatively, you can use the installed script directly:
298 
299```json
300{
301  "mcpServers": {
302    "mcp-clickhouse": {
303      "command": "mcp-clickhouse",
304      "env": {
305        "CLICKHOUSE_HOST": "<clickhouse-host>",
306        "CLICKHOUSE_PORT": "<clickhouse-port>",
307        "CLICKHOUSE_USER": "<clickhouse-user>",
308        "CLICKHOUSE_PASSWORD": "<clickhouse-password>",
309        "CLICKHOUSE_SECURE": "true",
310        "CLICKHOUSE_VERIFY": "true",
311        "CLICKHOUSE_CONNECT_TIMEOUT": "30",
312        "CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "30"
313      }
314    }
315  }
316}
317```
318 
319Note: Make sure to use the full path to the Python executable or the `mcp-clickhouse` script if they are not in your system PATH. You can find the paths using:
320- `which python3` for the Python executable
321- `which mcp-clickhouse` for the installed script
322 
323## Custom Middleware
324 
325You can add custom middleware to the MCP server without modifying the source code. FastMCP provides a middleware system that allows you to intercept and process MCP protocol messages (tool calls, resource reads, prompts, etc.).
326 
327### How to Use
328 
3291. Create a Python module with middleware classes extending `Middleware` and a `setup_middleware(mcp)` function:
330 
331```python
332# my_middleware.py
333import logging
334from fastmcp.server.middleware import Middleware, MiddlewareContext, CallNext
335 
336logger = logging.getLogger("my-middleware")
337 
338class LoggingMiddleware(Middleware):
339    """Log all tool calls."""
340    
341    async def on_call_tool(self, context: MiddlewareContext, call_next: CallNext):
342        tool_name = context.message.name if hasattr(context.message, 'name') else 'unknown'
343        logger.info(f"Calling tool: {tool_name}")
344        result = await call_next(context)
345        logger.info(f"Tool {tool_name} completed")
346        return result
347 
348def setup_middleware(mcp):
349    """Register middleware with the MCP server."""
350    mcp.add_middleware(LoggingMiddleware())
351```
352 
3532. Set the `MCP_MIDDLEWARE_MODULE` environment variable to the module name (without `.py` extension):
354 
355```json
356{
357  "mcpServers": {
358    "mcp-clickhouse": {
359      "command": "uv",
360      "args": ["run", "--with", "mcp-clickhouse", "--python", "3.10", "mcp-clickhouse"],
361      "env": {
362        "CLICKHOUSE_HOST": "<clickhouse-host>",
363        "CLICKHOUSE_USER": "<clickhouse-user>",
364        "CLICKHOUSE_PASSWORD": "<clickhouse-password>",
365        "MCP_MIDDLEWARE_MODULE": "my_middleware"
366      }
367    }
368  }
369}
370```
371 
3723. Ensure your middleware module is in Python's import path (e.g., in the same directory where the MCP server runs, or installed as a package).
373 
374### Example Middleware
375 
376An example middleware module is provided in `example_middleware.py` showing common patterns:
377- Logging all MCP requests
378- Logging tool calls specifically
379- Measuring request processing time
380 
381To use the example:
382```json
383"env": {
384  "MCP_MIDDLEWARE_MODULE": "example_middleware"
385}
386```
387 
388### Middleware Capabilities
389 
390The `Middleware` base class provides hooks for different MCP operations:
391 
392- `on_message(context, call_next)` - Called for all messages
393- `on_request(context, call_next)` - Called for all requests
394- `on_notification(context, call_next)` - Called for all notifications
395- `on_call_tool(context, call_next)` - Called when a tool is executed
396- `on_read_resource(context, call_next)` - Called when a resource is read
397- `on_get_prompt(context, call_next)` - Called when a prompt is retrieved
398- `on_list_tools(context, call_next)` - Called when listing tools
399- `on_list_resources(context, call_next)` - Called when listing resources
400- `on_list_resource_templates(context, call_next)` - Called when listing resource templates
401- `on_list_prompts(context, call_next)` - Called when listing prompts
402 
403Each hook receives a `MiddlewareContext` object containing the message and metadata, and a `call_next` function to continue the pipeline.
404 
405## Development
406 
4071. In `test-services` directory run `docker compose up -d` to start the ClickHouse cluster.
408 
4092. Add the following variables to a `.env` file in the root of the repository.
410 
411*Note: The use of the `default` user in this context is intended solely for local development purposes.*
412 
413```bash
414CLICKHOUSE_HOST=localhost
415CLICKHOUSE_PORT=8123
416CLICKHOUSE_USER=default
417CLICKHOUSE_PASSWORD=clickhouse
418```
419 
4203. Run `uv sync` to install the dependencies. To install `uv` follow the instructions [here](https://docs.astral.sh/uv/). Then do `source .venv/bin/activate`.
421 
4224. For easy testing with the MCP Inspector, run `fastmcp dev mcp_clickhouse/mcp_server.py` to start the MCP server.
423 
4245. To test with HTTP transport and the health check endpoint:
425   ```bash
426   # For development, disable authentication
427   CLICKHOUSE_MCP_SERVER_TRANSPORT=http CLICKHOUSE_MCP_AUTH_DISABLED=true python -m mcp_clickhouse.main
428 
429   # Or with authentication (generate a token first)
430   CLICKHOUSE_MCP_SERVER_TRANSPORT=http CLICKHOUSE_MCP_AUTH_TOKEN="your-token" python -m mcp_clickhouse.main
431 
432   # Then in another terminal:
433   # Without auth (if disabled):
434   curl http://localhost:8000/health
435 
436   # With auth:
437   curl -H "Authorization: Bearer your-token" http://localhost:8000/health
438   ```
439 
440### Environment Variables
441 
442The following environment variables are used to configure the ClickHouse and chDB connections:
443 
444#### ClickHouse Variables
445 
446##### Required Variables
447 
448* `CLICKHOUSE_HOST`: The hostname of your ClickHouse server
449* `CLICKHOUSE_USER`: The username for authentication
450* `CLICKHOUSE_PASSWORD`: The password for authentication
451 
452> [!CAUTION]
453> It is important to treat your MCP database user as you would any external client connecting to your database, granting only the minimum necessary privileges required for its operation. The use of default or administrative users should be strictly avoided at all times.
454 
455##### Optional Variables
456 
457* `CLICKHOUSE_PORT`: The port number of your ClickHouse server
458  * Default: `8443` if HTTPS is enabled, `8123` if disabled
459  * Usually doesn't need to be set unless using a non-standard port
460* `CLICKHOUSE_ROLE`: The role to use for authentication
461  * Default: None
462  * Set this if your user requires a specific role
463* `CLICKHOUSE_SECURE`: Enable/disable HTTPS connection
464  * Default: `"true"`
465  * Set to `"false"` for non-secure connections
466* `CLICKHOUSE_VERIFY`: Enable/disable SSL certificate verification
467  * Default: `"true"`
468  * Set to `"false"` to disable certificate verification (not recommended for production)
469  * TLS certificates: The package uses your operating system trust store for TLS certificate verification via `truststore`. We call `truststore.inject_into_ssl()` at startup to ensure proper certificate handling. Python’s default SSL behavior is used as a fallback only if an unexpected error occurs.
470* `CLICKHOUSE_CONNECT_TIMEOUT`: Connection timeout in seconds
471  * Default: `"30"`
472  * Increase this value if you experience connection timeouts
473* `CLICKHOUSE_SEND_RECEIVE_TIMEOUT`: Send/receive timeout in seconds
474  * Default: `"300"`
475  * Increase this value for long-running queries
476* `CLICKHOUSE_DATABASE`: Default database to use
477  * Default: None (uses server default)
478  * Set this to automatically connect to a specific database
479* `CLICKHOUSE_MCP_SERVER_TRANSPORT`: Sets the transport method for the MCP server.
480  * Default: `"stdio"`
481  * Valid options: `"stdio"`, `"http"`, `"sse"`. This is useful for local development with tools like MCP Inspector.
482* `CLICKHOUSE_MCP_BIND_HOST`: Host to bind the MCP server to when using HTTP or SSE transport
483  * Default: `"127.0.0.1"`
484  * Set to `"0.0.0.0"` to bind to all network interfaces (useful for Docker or remote access)
485  * Only used when transport is `"http"` or `"sse"`
486* `CLICKHOUSE_MCP_BIND_PORT`: Port to bind the MCP server to when using HTTP or SSE transport
487  * Default: `"8000"`
488  * Only used when transport is `"http"` or `"sse"`
489* `CLICKHOUSE_MCP_QUERY_TIMEOUT`: Timeout in seconds for SELECT tools
490  * Default: `"30"`
491  * Increase this if you see `Query timed out after ...` errors for heavy queries
492* `CLICKHOUSE_MCP_AUTH_TOKEN`: Authentication token for HTTP/SSE transports
493  * Default: None
494  * **Required** when using HTTP or SSE transport (unless `CLICKHOUSE_MCP_AUTH_DISABLED=true`)
495  * Generate using `uuidgen` or `openssl rand -hex 32`
496  * Clients must send this token in the `Authorization: Bearer <token>` header
497* `CLICKHOUSE_MCP_AUTH_DISABLED`: Disable authentication for HTTP/SSE transports
498  * Default: `"false"` (authentication is enabled)
499  * Set to `"true"` to disable authentication for local development/testing only
500  * **WARNING:** Only use for local development. Do not disable when exposed to networks
501* `CLICKHOUSE_ENABLED`: Enable/disable ClickHouse functionality
502  * Default: `"true"`
503  * Set to `"false"` to disable ClickHouse tools when using chDB only
504* `CLICKHOUSE_ALLOW_WRITE_ACCESS`: Allow write operations (DDL and DML)
505  * Default: `"false"`
506  * Set to `"true"` to allow DDL (CREATE, ALTER, DROP) and DML (INSERT, UPDATE, DELETE) operations
507  * When disabled (default), queries run with `readonly=1` setting to prevent data modifications
508* `CLICKHOUSE_ALLOW_DROP`: Allow destructive operations (DROP TABLE, DROP DATABASE, DROP VIEW, DROP DICTIONARY, TRUNCATE TABLE)
509  * Default: `"false"`
510  * Only takes effect when `CLICKHOUSE_ALLOW_WRITE_ACCESS=true` is also set
511  * Set to `"true"` to explicitly allow destructive DROP and TRUNCATE operations
512  * This is a safety feature to prevent accidental data deletion during AI exploration
513 
514#### Middleware Variables
515 
516* `MCP_MIDDLEWARE_MODULE`: Python module name containing custom middleware to inject into the MCP server
517  * Default: None (no middleware loaded)
518  * Set to the module name (without `.py` extension) of your middleware module
519  * The module must provide a `setup_middleware(mcp)` function
520  * See [Custom Middleware](#custom-middleware) for details and examples
521 
522#### chDB Variables
523 
524* `CHDB_ENABLED`: Enable/disable chDB functionality
525  * Default: `"false"`
526  * Set to `"true"` to enable chDB tools
527* `CHDB_DATA_PATH`: The path to the chDB data directory
528  * Default: `":memory:"` (in-memory database)
529  * Use `:memory:` for in-memory database
530  * Use a file path for persistent storage (e.g., `/path/to/chdb/data`)
531 
532#### Example Configurations
533 
534For local development with Docker:
535 
536```env
537# Required variables
538CLICKHOUSE_HOST=localhost
539CLICKHOUSE_USER=default
540CLICKHOUSE_PASSWORD=clickhouse
541 
542# Optional: Override defaults for local development
543CLICKHOUSE_SECURE=false  # Uses port 8123 automatically
544CLICKHOUSE_VERIFY=false
545```
546 
547For ClickHouse Cloud:
548 
549```env
550# Required variables
551CLICKHOUSE_HOST=your-instance.clickhouse.cloud
552CLICKHOUSE_USER=default
553CLICKHOUSE_PASSWORD=your-password
554 
555# Optional: These use secure defaults
556# CLICKHOUSE_SECURE=true  # Uses port 8443 automatically
557# CLICKHOUSE_DATABASE=your_database
558```
559 
560For ClickHouse SQL Playground:
561 
562```env
563CLICKHOUSE_HOST=sql-clickhouse.clickhouse.com
564CLICKHOUSE_USER=demo
565CLICKHOUSE_PASSWORD=
566# Uses secure defaults (HTTPS on port 8443)
567```
568 
569For chDB only (in-memory):
570 
571```env
572# chDB configuration
573CHDB_ENABLED=true
574CLICKHOUSE_ENABLED=false
575# CHDB_DATA_PATH defaults to :memory:
576```
577 
578For chDB with persistent storage:
579 
580```env
581# chDB configuration
582CHDB_ENABLED=true
583CLICKHOUSE_ENABLED=false
584CHDB_DATA_PATH=/path/to/chdb/data
585```
586 
587For MCP Inspector or remote access with HTTP transport:
588 
589```env
590CLICKHOUSE_HOST=localhost
591CLICKHOUSE_USER=default
592CLICKHOUSE_PASSWORD=clickhouse
593CLICKHOUSE_MCP_SERVER_TRANSPORT=http
594CLICKHOUSE_MCP_BIND_HOST=0.0.0.0  # Bind to all interfaces
595CLICKHOUSE_MCP_BIND_PORT=4200  # Custom port (default: 8000)
596CLICKHOUSE_MCP_AUTH_TOKEN=your-generated-token  # Required for HTTP/SSE
597```
598 
599For local development with HTTP transport (authentication disabled):
600 
601```env
602CLICKHOUSE_HOST=localhost
603CLICKHOUSE_USER=default
604CLICKHOUSE_PASSWORD=clickhouse
605CLICKHOUSE_MCP_SERVER_TRANSPORT=http
606CLICKHOUSE_MCP_AUTH_DISABLED=true  # Only for local development!
607```
608 
609When using HTTP transport, the server will run on the configured port (default 8000). For example, with the above configuration:
610- MCP endpoint: `http://localhost:4200/mcp`
611- Health check: `http://localhost:4200/health`
612 
613You can set these variables in your environment, in a `.env` file, or in the Claude Desktop configuration:
614 
615```json
616{
617  "mcpServers": {
618    "mcp-clickhouse": {
619      "command": "uv",
620      "args": [
621        "run",
622        "--with",
623        "mcp-clickhouse",
624        "--python",
625        "3.10",
626        "mcp-clickhouse"
627      ],
628      "env": {
629        "CLICKHOUSE_HOST": "<clickhouse-host>",
630        "CLICKHOUSE_USER": "<clickhouse-user>",
631        "CLICKHOUSE_PASSWORD": "<clickhouse-password>",
632        "CLICKHOUSE_DATABASE": "<optional-database>",
633        "CLICKHOUSE_MCP_SERVER_TRANSPORT": "stdio",
634        "CLICKHOUSE_MCP_BIND_HOST": "127.0.0.1",
635        "CLICKHOUSE_MCP_BIND_PORT": "8000"
636      }
637    }
638  }
639}
640```
641 
642Note: The bind host and port settings are only used when transport is set to "http" or "sse".
643 
644### Running tests
645 
646```bash
647uv sync --all-extras --dev # install dev dependencies
648uv run ruff check . # run linting
649 
650docker compose up -d test_services # start ClickHouse
651uv run pytest -v tests
652uv run pytest -v tests/test_tool.py # ClickHouse only
653uv run pytest -v tests/test_chdb_tool.py # chDB only
654```
655 
656## YouTube Overview
657 
658[![YouTube](http://i.ytimg.com/vi/y9biAm_Fkqw/hqdefault.jpg)](https://www.youtube.com/watch?v=y9biAm_Fkqw)
659