Provides tools for connecting to a ClickHouse database and executing SQL queries, with support for multiple queries and JSON-formatted results.
Clickhouse MCP server
A Clickhouse database MCP server project.
Installation
You can install the package using uv
:
Or using pip
:
Components
Tools
The server provides two tools:
connect_database
: Connects to a specific Clickhouse databasedatabase
parameter: Name of the database to connect to (string)- Returns a confirmation message when connection is successful
execute_query
: Executes Clickhouse queriesquery
parameter: SQL query/queries to execute (string)- Returns query results in JSON format
- Multiple queries can be sent separated by semicolons
Configuration
The server uses the following environment variables:
CLICKHOUSE_HOST
: Clickhouse server address (default: "localhost")CLICKHOUSE_USER
: Clickhouse username (default: "root")CLICKHOUSE_PASSWORD
: Clickhouse password (default: "")CLICKHOUSE_DATABASE
: Initial database (optional)CLICKHOUSE_READONLY
: Read-only mode (set to 1/true to enable, default: false)
Quickstart
Installation
Claude Desktop
MacOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json
Windows: %APPDATA%/Claude/claude_desktop_config.json
Installing via Smithery
To install Clickhouse Database Integration Server for Claude Desktop automatically via Smithery:
Development
Building and Publishing
To prepare the package for distribution:
- Sync dependencies and update lockfile:
- Build package distributions:
This will create source and wheel distributions in the dist/
directory.
- Publish to PyPI:
Note: You'll need to set PyPI credentials via environment variables or command flags:
- Token:
--token
orUV_PUBLISH_TOKEN
- Or username/password:
--username
/UV_PUBLISH_USERNAME
and--password
/UV_PUBLISH_PASSWORD
Debugging
Since MCP servers run over stdio, debugging can be challenging. For the best debugging experience, we strongly recommend using the MCP Inspector.
You can launch the MCP Inspector via npm
with this command:
Upon launching, the Inspector will display a URL that you can access in your browser to begin debugging.
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
An MCP server implementation that enables Claude AI to interact with Clickhouse databases. Features include secure database connections, query execution, read-only mode support, and multi-query capabilities.
Related Resources
Related MCP Servers
- AsecurityFlicenseAqualityAn MCP server that allows Claude AI to perform filesystem operations including reading, writing, listing, moving files, and searching directories within specified allowed paths.Last updated -9101JavaScript
- AsecurityAlicenseAqualityClickUp MCP Server enables AI assistants to seamlessly interact with your ClickUp workspace. This powerful integration allows Claude to create and manage tasks, access documents, organize folders and lists, add comments, and handle checklists—all through natural conversation.Last updated -4261318TypeScriptMIT License
- -securityAlicense-qualityAn MCP server that implements Claude Code-like functionality, allowing the AI to analyze codebases, modify files, execute commands, and manage projects through direct file system interactions.Last updated -224PythonMIT License
- -securityFlicense-qualityAn MCP server that integrates with Claude to provide smart documentation search capabilities across multiple AI/ML libraries, allowing users to retrieve and process technical information through natural language queries.Last updated -Python