MCP server for ClickHouse

MCP server for ClickHouse is an application that provides AI assistants with access to ClickHouse databases via the standard Model Context Protocol (MCP). The server is deployed on a virtual machine in Yandex Cloud and connects to an existing ClickHouse cluster.

Key Features and Benefits

• Yandex AI Studio Integration. The MCP server integrates with AI Studio MCP Servers — connect it to your AI agents in just a few clicks.
• AI Assistant Integration. Enables Claude, ChatGPT, and other AI models to execute queries against ClickHouse, analyze data, and retrieve database schema information.
• Bearer Token Authorization. All requests to the MCP server are protected with a Bearer token stored in Yandex Lockbox.
• Secure ClickHouse Connection. The ClickHouse connection password is stored in Yandex Lockbox and retrieved at startup. SSL/TLS support for encrypted connections. Optional CA certificate from Certificate Manager for non-Managed ClickHouse^®.
• Standard MCP Protocol. Uses the open Model Context Protocol for AI model interaction, ensuring compatibility with a wide range of clients.
• HTTP Transport. The MCP server is accessible on port 8000 (HTTP), simplifying integration with various clients and tools.
• Minimal Resources. The application runs on a virtual machine with minimal configuration (2 vCPU, 2 GB RAM), reducing infrastructure costs.

1. Make sure you have a running ClickHouse cluster (Managed Service for ClickHouse or self-hosted).
2. Create a secret in Yandex Lockbox to store the ClickHouse password. The secret must contain a clickhouse_password key with the password value.
3. Create a secret in Yandex Lockbox to store the Bearer token for authorization. The secret must contain a bearer_token key with an arbitrary token value.
4. (Optional) If using non-Managed ClickHouse^® and an additional CA certificate is required, upload a certificate to Yandex Certificate Manager.
5. Create a service account with the roles compute.editor, iam.serviceAccounts.admin, lockbox.payloadViewer, vpc.admin (the admin role includes all the specified roles).
6. In the management console select the Cloud Apps service.
7. In the left panel, select Application Store.
8. Select MCP ClickHouse and click the Use button.
9. Specify:
   • Application name.
   • (Optional) Application description.
   • The service account created earlier.
   • The cloud subnet where the virtual machine will be deployed.
   • Lockbox secret ID containing the Bearer token for authorization.
   • (Optional) Certificate from Certificate Manager for the ClickHouse^® connection.
   • ClickHouse host (FQDN).
   • ClickHouse port (default is 9440).
   • ClickHouse username (default is default).
   • Lockbox secret ID containing the ClickHouse password.
10. Click the Install button and wait for the application to install.
11. After installation, the MCP server will be available at http://<vm-ip>:8000.
12. Configure your AI client (Claude Desktop, Cursor, etc.) to connect to the MCP server, specifying the Authorization: Bearer <your-token> header.

• Analyzing data in ClickHouse using an AI assistant (Claude, ChatGPT).
• Automatic SQL query generation for ClickHouse via natural language.
• Exploring ClickHouse database schema with AI.
• Monitoring and analyzing logs stored in ClickHouse.
• Building reports and visualizations based on ClickHouse data.

Yandex Cloud technical support is available 24/7. The types of requests you can submit and the appropriate response time depend on your pricing plan. You can switch to the paid support plan in the management console. You can learn more about the technical support terms here.