Skip to content

Commit 6aafa9e

Browse files
BlargianBlargian
authored
Merge pull request #4071 from mneedham/claude-desktop-mcp
Claude Desktop MCP example
2 parents 0a7afb1 + 589e38c commit 6aafa9e

File tree

8 files changed

+317
-103
lines changed

8 files changed

+317
-103
lines changed

‎docs/use-cases/AI_ML/MCP/claude-desktop.md

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
---
2+
slug: /use-cases/AI/MCP/claude-desktop
3+
sidebar_label: 'Claude Desktop and ClickHouse MCP'
4+
title: 'Set Up ClickHouse MCP Server with Claude Desktop'
5+
pagination_prev: null
6+
pagination_next: null
7+
description: 'This guide explains how to set up Claude Desktop with a ClickHouse MCP server.'
8+
keywords: ['AI', 'Librechat', 'MCP']
9+
show_related_blogs: true
10+
---
11+
12+
import {CardHorizontal} from '@clickhouse/click-ui/bundled'
13+
import Link from '@docusaurus/Link';
14+
import Image from '@theme/IdealImage';
15+
import ClaudeDesktopConfig from '@site/static/images/use-cases/AI_ML/MCP/claude-desktop-config.png';
16+
import FindMCPServers from '@site/static/images/use-cases/AI_ML/MCP/find-mcp-servers.gif';
17+
import MCPPermission from '@site/static/images/use-cases/AI_ML/MCP/mcp-permission.png';
18+
import ClaudeConversation from '@site/static/images/use-cases/AI_ML/MCP/claude-conversation.png';
19+
20+
# Using ClickHouse MCP server with Claude Desktop
21+
22+
> This guide explains how to set up Claude Desktop with a ClickHouse MCP server using uv
23+
> and connect it to the ClickHouse example datasets.
24+
25+
<VerticalStepper headerLevel="h2">
26+
27+
## Install uv {#install-uv}
28+
29+
You will need to install [uv](https://docs.astral.sh/uv/) to follow the instructions in this guide.
30+
If you don't want to use uv, you will need to update the MCP Server config to use an alternative package manager.
31+
32+
## Download Claude Desktop {#download-claude-desktop}
33+
34+
You'll also need to install the Claude Desktop app, which you can download from the [Claude Desktop website](https://claude.ai/desktop).
35+
36+
## Configuring ClickHouse MCP server {#configure-clickhouse-mcp-server}
37+
38+
Once you've got Claude Desktop installed, it's time to configure the [ClickHouse MCP server](https://github.com/ClickHouse/mcp-clickhouse).
39+
We can do this via the [Claude Desktop configuration file](https://claude.ai/docs/configuration).
40+
41+
To find this file, first go to the settings page (`Cmd+,` on a Mac) and then click on the `Developer` tab on the left menu.
42+
You'll then see the following screen, on which you'll need to click on the `Edit config` button:
43+
44+
<Image img={ClaudeDesktopConfig} alt="Claude Desktop configuration" size="md" />
45+
46+
This will take you to a directory containing the configuration file (`claude_desktop_config.json`).
47+
The first time you open that file, it will likely contain the following content:
48+
49+
```json
50+
{
51+
"mcpServers": {}
52+
}
53+
```
54+
55+
The `mcpServers` dictionary takes in the name of an MCP Server as a key, and a dictionary of configuration options as a value.
56+
For example, the ClickHouse MCP server configuration connecting to the ClickHouse Playground would look like this:
57+
58+
```json
59+
{
60+
"mcpServers": {
61+
"mcp-clickhouse": {
62+
"command": "uv",
63+
"args": [
64+
"run",
65+
"--with",
66+
"mcp-clickhouse",
67+
"--python",
68+
"3.10",
69+
"mcp-clickhouse"
70+
],
71+
"env": {
72+
"CLICKHOUSE_HOST": "sql-clickhouse.clickhouse.com",
73+
"CLICKHOUSE_PORT": "8443",
74+
"CLICKHOUSE_USER": "demo",
75+
"CLICKHOUSE_PASSWORD": "",
76+
"CLICKHOUSE_SECURE": "true",
77+
"CLICKHOUSE_VERIFY": "true",
78+
"CLICKHOUSE_CONNECT_TIMEOUT": "30",
79+
"CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "30"
80+
}
81+
}
82+
}
83+
}
84+
```
85+
86+
Once you've updated the config, you'll need to restart Claude Desktop for the changes to take effect.
87+
88+
:::warning
89+
Depending on how you installed `uv`, you might receive the following error when restarting Claude Desktop:
90+
91+
```text
92+
MCP mcp-clickhouse: spawn uv ENOENT
93+
```
94+
95+
If that happens, you'll need to update the `command` to have the full path to `uv`. e.g. if you've installed via Cargo, it will be `/Users/<username>/.cargo/bin/uv`
96+
:::
97+
98+
## Using ClickHouse MCP server {#using-clickhouse-mcp-server}
99+
100+
Once you've restarted Claude Desktop, you can find the ClickHouse MCP server by clicking on the `Search and tools` icon:
101+
102+
<Image img={FindMCPServers} alt="Find MCP servers" size="md" />
103+
<br/>
104+
105+
You can then choose whether to disable all or some of the tools.
106+
107+
Now we're ready to ask Claude some questions that will result in it using the ClickHouse MCP server.
108+
For example, we could ask it `What's the most interesting dataset in the SQL playground?`.
109+
110+
Claude will ask us to confirm the use of each tool in the MCP Server the first time that it's called:
111+
112+
<Image img={MCPPermission} alt="Give permission to use the list_databases tool" size="md" />
113+
114+
Below you can see part of a conversation that includes some tool calls to the ClickHouse MCP Server:
115+
116+
<Image img={ClaudeConversation} alt="Claude conversation" size="md" />
117+
118+
</VerticalStepper>

‎docs/use-cases/AI_ML/index.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,13 @@
11
---
2-
description: 'Landing page for Machine learning and GenAI use case guides'
2+
description: 'Landing page for Machine Learning and GenAI use case guides'
33
pagination_prev: null
44
pagination_next: null
55
slug: /use-cases/AI
66
title: 'Machine learning and GenAI'
77
keywords: ['machine learning', 'genAI', 'AI']
88
---
99

10-
# Machine learning and GenAI
10+
# Machine Learning and GenAI
1111

1212
ClickHouse is ideally suited as a real-time database to power Machine Learning workloads.
1313
With ClickHouse, it's easier than ever to unleash GenAI on your analytics data.

‎scripts/settings/beta-settings.sql

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -5,15 +5,15 @@ FORMAT TSVRaw;
55

66
-- Then append the table content
77
WITH
8-
experimental_session_settings AS
8+
beta_session_settings AS
99
(
1010
SELECT
1111
format('[{}](/operations/settings/settings#{})', name, name) AS Name,
1212
format('`{}`', ifNull(default, ' ')) AS Default
1313
FROM system.settings
14-
WHERE tier = 'Beta' AND alias_for=''
14+
WHERE tier = 'Beta' AND alias_for='' AND name NOT LIKE 'vector_search_with_rescoring'
1515
),
16-
experimental_mergetree_settings AS
16+
beta_mergetree_settings AS
1717
(
1818
SELECT
1919
format('[{}](/operations/settings/merge-tree-settings#{})', name, name) AS Name,
@@ -24,10 +24,10 @@ WHERE tier = 'Beta'
2424
combined AS
2525
(
2626
SELECT *
27-
FROM experimental_session_settings
27+
FROM beta_session_settings
2828
UNION ALL
2929
SELECT *
30-
FROM experimental_mergetree_settings
30+
FROM beta_mergetree_settings
3131
ORDER BY Name ASC
3232
)
3333
SELECT concat('| ', Name, ' | ', Default, ' |')

0 commit comments

Comments
 (0)