一、前言

随着 AI 应用平台（如 Dify）逐渐被企业采用，让 LLM 能直接访问数据库并执行 SQL 成为关键能力。OpenAI 推出的 MCP（Model Context Protocol）模型上下文协议，为 LLM 和外部系统之间提供了安全、规范的能力接口。

本篇文章将手把手带你搭建以下完整架构：

[Dify 应用平台]
        ↓ HTTP/SSE
[MCP SSE 插件（Dify 内置）]
        ↓ HTTP/SSE
[mcp-proxy（协议转换层）]
        ↓ stdio
[ClickHouse MCP Server（mcp-clickhouse）]
        ↓ HTTP (8123)
[ClickHouse 数据库]

本教程内容包括：

• MCP 原理概念解释

• mcp-proxy 配置

• mcp-clickhouse 环境变量

• Dify 插件配置

• 全链路排查方法

• 常见 SSL 错误分析

参考链接：

https://github.com/sparfenyuk/mcp-proxy?tab=readme-ov-file

MCP SSE / StreamableHTTP - Dify Marketplace

ClickHouse/mcp-clickhouse: Connect ClickHouse to your AI assistants.

Dify 中使用 MCP 协议访问 ClickHouse 搭建完整教程 | ApFramework

---

二、系统架构解析

先看一下整体架构图（ASCII 版本）：

+-----------------+               +---------------------+
|   Dify 平台      |  SSE/HTTP     |   MCP SSE 插件        |
| （用户界面）     | <-----------> | （Dify 内部）          |
+-----------------+               +---------------------+
                                          |
                                          | HTTP/SSE
                                          v
                                +---------------------+
                                |      mcp-proxy      |
                                |  （协议转换层）       |
                                +---------------------+
                                          |
                                          | stdio（双向管道）
                                          v
                        +--------------------------------------+
                        |      ClickHouse MCP Server           |
                        |      (mcp-clickhouse Python 包)      |
                        +--------------------------------------+
                                          |
                                          | HTTP (8123)
                                          v
                                +---------------------+
                                |   ClickHouse 数据库  |
                                +---------------------+

架构关键点说明

模块	作用
Dify	提供 LLM + 工具调用接口
MCP SSE 插件	把 Dify 的工具调用转换成 MCP SSE
mcp-proxy	把 SSE 转换为 stdio（和 MCP Server 通信）
mcp-clickhouse	实现 ClickHouse 的工具层（SQL 查询、数据处理）
ClickHouse	最终数据库

完整链路清晰分层，便于调试与扩展。

---

三、安装和准备环境

1. 安装 mcp-clickhouse（Python）

pip install mcp-clickhouse

或升级：

pip install --upgrade mcp-clickhouse

2. 安装 mcp-proxy

pip install mcp-proxy

3. 检查 ClickHouse 是否可访问

curl http://192.168.101.150:8123

返回 OK 即表示 HTTP 8123 正常。

---

四、mcp-clickhouse 核心配置

mcp-clickhouse 支持多种部署方式，你需要根据数据库是否有 HTTPS、是否在内网、是否有证书来决定环境变量的值。

mcp-clickhouse 默认会采用 HTTPS / 8443 连接 ClickHouse。

但很多企业环境使用的是：

http://IP:8123 （无 SSL）

因此必须关闭 secure 配置：

CLICKHOUSE_SECURE=false
CLICKHOUSE_VERIFY=false

完整环境变量如下（重要）：

export CLICKHOUSE_HOST=your-clickhouse-host
export CLICKHOUSE_PORT=8123
export CLICKHOUSE_USER=default
export CLICKHOUSE_PASSWORD=your-password

# 如果你的 ClickHouse 使用 HTTP，就必须关闭这两个
export CLICKHOUSE_SECURE=false
export CLICKHOUSE_VERIFY=false

# MCP 使用 stdio（通常给 mcp-proxy 用）
export CLICKHOUSE_MCP_SERVER_TRANSPORT=stdio

🔍 环境变量解释（非常重要）

变量	含义	你的实际可替换内容
CLICKHOUSE_HOST	数据库地址，可是域名或IP	如：10.0.0.15 / clickhouse.company.com
CLICKHOUSE_PORT	数据库端口	HTTP=8123 / HTTPS=8443
CLICKHOUSE_USER	用户名	如：default 或业务帐号
CLICKHOUSE_PASSWORD	密码	自己的密码
CLICKHOUSE_SECURE	是否使用 HTTPS	内网一般 false
CLICKHOUSE_VERIFY	是否校验证书	自签名证书一般 false
CLICKHOUSE_MCP_SERVER_TRANSPORT	MCP 传输方式	mcp-proxy 用 stdio

启动 MCP Server：

python -m mcp_clickhouse.main

如果启动成功，会看到：

Transport: STDIO
ClickHouse tools registered

---

五、mcp-proxy 配置（核心环节）

进入 mcp-proxy 目录：

cd mcp-proxy

编辑配置文件：

nano config.json

写入如下内容：

{
  "servers": {
    "clickhouse": {
      "command": "python3",
      "args": ["-m", "mcp_clickhouse.main"],
      "env": {
        "CLICKHOUSE_HOST": "your-clickhouse-host",
        "CLICKHOUSE_PORT": "8123",
        "CLICKHOUSE_USER": "default",
        "CLICKHOUSE_PASSWORD": "your-password",
        "CLICKHOUSE_SECURE": "false",
        "CLICKHOUSE_VERIFY": "false",
        "CLICKHOUSE_MCP_SERVER_TRANSPORT": "stdio"
      }
    }
  }
}

注意：

• env 中的变量等同于你 export 的变量

• 现在 mcp-proxy 工作模式是 SSE ↔ stdio

🔍 config.json 每项解释

1. "command": "python3"

表示 mcp-proxy 启动这个 MCP 服务器时，会执行：

python3 -m mcp_clickhouse.main

👉 替换逻辑：

场景	command 应该填什么？
你系统里 python3 是全局命令（常见）	"python3"
你使用虚拟环境 venv	"/path/to/venv/bin/python"
你用 uv 运行	"uv"（配合 args 调整）

2. "args": ["-m", "mcp_clickhouse.main"]

说明用 Python 模块方式运行 MCP Server。

如果你安装后可以直接执行：

mcp-clickhouse

也可以：

"command": "mcp-clickhouse"

3. "env" 内的变量

一律对应 mcp-clickhouse 的配置。

如果你不想写在 config.json 里，也可以用系统变量覆盖。

启动 mcp-proxy：

mcp-proxy -c config.json

如果成功，会显示：

Registered server: clickhouse
Proxy is now listening...

 六、mcp-proxy 启动命令的多种模式（含使用场景）

mcp-proxy 支持多种启动方式，下面详细解释。

---

🟦 （1）最简单启动方式：本机调试

适用于：

• 你在本机使用 Claude Desktop / MCP Inspector

• 不需要远程访问

• 本机端口不暴露

命令：

mcp-proxy -c config.json

特点：

• 默认 host：127.0.0.1

• 默认端口：8080

• 仅本机可访问

---

🟩 （2）适合远程访问、适合 Dify、适合容器环境

mcp-proxy \
  --named-server-config /root/mcp-workspace/mcp-proxy/config.json \
  --host 0.0.0.0 \
  --port 45195

🔍 参数解释：

参数	作用
--named-server-config	使用一个包含多个服务器定义的配置文件
--host 0.0.0.0	开放到所有网卡（必须用于 Docker / Dify / 局域网访问）
--port 45195	指定 SSE 服务端口，让客户端去连接它

👉 使用场景：

场景	是否适用
Dify 需要访问 mcp-proxy	✔ 必须
浏览器 / 其他服务器访问	✔ 必须
Docker 容器	✔ 必须
云服务器	✔ 强烈推荐
本机调试	不一定需要

所以你使用的是 跨机器访问的正式部署方式。

---

🟧 （3）SSE 模式显式指定

如果你要强制 SSE，可以加：

--transport sse

适用于：

• 某些前端只支持 SSE

• 某些防火墙禁止 WebSocket

---

🟥 （4）使用自定义 HTTP 路径

默认 MCP endpoint 路径：

/mcp

如需改成 /api/mcp：

mcp-proxy --path /api/mcp ...

适用场景：

• Nginx 反向代理

• 部署在子路径

• 多个 MCP Proxy 同时工作

---

七、❗ 只有 mcp-proxy 使用 --host 0.0.0.0，其他机器才能访问。

---

八、常见启动方式选择表

你当前的部署情况	推荐启动命令
本地开发	mcp-proxy -c config.json
Dify + MCP（同一台机器）	mcp-proxy -c config.json --host 0.0.0.0
Dify 在另一台服务器	mcp-proxy --named-server-config config.json --host 0.0.0.0 --port 45195
Docker 容器部署	mcp-proxy --host 0.0.0.0 --port 8080
多个 MCP Servers	使用 --named-server-config
需要自定义路径	加 --path

---

九、Dify 中配置 MCP SSE插件

在 Dify 后台 → 插件 → 添加 MCP SSE 插件

Dify 在另一台服务器时的示例：

{   "clickhouse": 
    {     "url": "http://192.168.101.150:45195/servers/clickhouse/sse",     
          "headers": {},     
          "timeout": 60,     
          "sse_read_timeout": 300   
    } 
}

保存后，Dify 会自动：

1. 建立 SSE 连接 → mcp-proxy

2. mcp-proxy 调用你的 mcp-clickhouse

3. mcp-clickhouse 调用 ClickHouse 运行 SQL

创建的应用中即可直接调用 SQL 工具。

---

十、测试数据库查询（Dify 内）

在 Dify 的 LLM 调试页面输入：

查询一下 system.tables

你会看到 LLM 自动选择工具：

Tool: run_select_query
SQL: SELECT * FROM system.tables LIMIT 10

并得到正常返回。

---

十一、常见错误与排查（非常重要）

❌ 1. SSL wrong version number

[SSL: WRONG_VERSION_NUMBER]

原因：

• mcp-clickhouse 默认使用 HTTPS（8443）

• 你的 ClickHouse 是 HTTP（8123）

解决：

CLICKHOUSE_SECURE=false
CLICKHOUSE_VERIFY=false

---

❌ 2. mcp-proxy 无法启动

检查：

mcp-proxy -c config.json

是否看到：

Registered server

---

❌ 3. Dify 报 "timeout"

检查：

mcp-proxy 是否运行
mcp-clickhouse 是否运行
ClickHouse 是否能 curl

---

十二、总结

本教程实现了：

✔ Dify 通过 MCP 接入 ClickHouse
✔ 使用 mcp-proxy 做协议转换（SSE ↔ stdio）
✔ 使用 mcp-clickhouse 执行 SQL
✔ 最终实现效果：

👉 LLM 可直接查询 ClickHouse
👉 查询结果实时返回到 Dify
👉 无需暴露数据库密码给 Dify
👉 安全、可控、可扩展