> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 为 Ollama 配置 ClickHouse MCP 服务器

> 本指南介绍如何为 Ollama 配置 ClickHouse MCP 服务器。

> 本指南介绍如何将 ClickHouse MCP 服务器与 Ollama 配合使用。

<Steps>
  <Step title="安装 Ollama" id="install-ollama">
    Ollama 是一个可让你在本机运行大型语言模型 (LLM) 的库。
    它提供了[丰富的模型选择](https://ollama.com/library)，而且使用起来很简单。

    你可以从[下载页面](https://ollama.com/download)下载适用于 Mac、Windows 或 Linux 的 Ollama。

    运行 Ollama 后，它会在后台启动一个本地服务器，你可以用它来运行模型。
    或者，你也可以通过运行 `ollama serve` 手动启动服务器。

    安装完成后，你可以像这样将模型拉取到本机：

    ```bash theme={null}
    ollama pull qwen3:8b
    ```

    如果本地机器上还没有该模型，这会将其拉取到本地。
    下载完成后，你可以像这样运行该模型：

    ```bash theme={null}
    ollama run qwen3:8b
    ```

    <Note>
      只有[支持工具的模型](https://ollama.com/search?c=tools)才能与 MCP servers 配合工作。
    </Note>

    我们可以像这样列出已下载的模型：

    ```bash theme={null}
    ollama ls
    ```

    ```text theme={null}
    NAME                       ID              SIZE      MODIFIED
    qwen3:latest               500a1f067a9f    5.2 GB    3 days ago
    ```

    我们可以使用以下命令查看已下载模型的更多信息：

    ```bash theme={null}
    ollama show qwen3
    ```

    ```text theme={null}
      Model
        architecture        qwen3
        parameters          8.2B
        context length      40960
        embedding length    4096
        quantization        Q4_K_M

      Capabilities
        completion
        tools

      Parameters
        repeat_penalty    1
        stop              "<|im_start|>"
        stop              "<|im_end|>"
        temperature       0.6
        top_k             20
        top_p             0.95

      License
        Apache License
        Version 2.0, January 2004
    ```

    从该输出可以看出，默认的 qwen3 模型参数略多于 80 亿。
  </Step>

  <Step title="安装 MCPHost" id="install-mcphost">
    在撰写本文时 (2025 年 7 月) ，尚无可将 Ollama 与 MCP 服务器配合使用的原生功能。
    不过，我们可以使用 [MCPHost](https://github.com/mark3labs/mcphost) 让 Ollama 模型与 MCP 服务器配合运行。

    MCPHost 是一个 Go 应用程序，因此你需要确保本机已[安装 Go](https://go.dev/doc/install)。
    然后，你可以运行以下命令来安装 MCPHost：

    ```bash theme={null}
    go install github.com/mark3labs/mcphost@latest
    ```

    该可执行文件会安装到 `~/go/bin` 下，因此需要确保该目录已加入 PATH。
  </Step>

  <Step title="配置 ClickHouse MCP 服务器" id="configure-clickhouse-mcp-server">
    我们可以在 YAML 或 JSON 文件中使用 MCPHost 来配置 MCP 服务器。
    MCPHost 会按以下顺序在你的主目录中查找配置文件：

    1. `.mcphost.yml` 或 `.mcphost.json` (推荐)
    2. `.mcp.yml` 或 `.mcp.json` (向后兼容)

    它使用的语法与标准 MCP 配置文件类似。
    下面是一个 ClickHouse MCP 服务器配置示例，我们将把它保存到 `~/.mcphost.json` 文件中：

    ```json theme={null}
    {
      "mcpServers": {
        "mcp-ch": {
          "type": "local",
          "command": ["uv",
            "run",
            "--with",
            "mcp-clickhouse",
            "--python",
            "3.10",
            "mcp-clickhouse"
          ]
        }
      }
    }
    ```

    与标准的 MCP 配置文件相比，主要区别在于需要指定一个 `type`。
    `type` 用于表明 MCP 服务器使用的传输类型。

    * `local` → stdio 传输
    * `remote` → 流式传输
    * `builtin` → 进程内传输

    我们还需要配置以下环境变量：

    ```bash theme={null}
    export CLICKHOUSE_HOST=sql-clickhouse.clickhouse.com
    export CLICKHOUSE_USER=demo
    export CLICKHOUSE_PASSWORD=""
    ```

    <Note>
      理论上，你应该可以在 MCP 配置文件的 `environment` 键下设置这些变量，但我们发现这种方式并不生效。
    </Note>
  </Step>

  <Step title="运行 MCPHost" id="running-mcphost">
    完成 ClickHouse MCP 服务器配置后，可通过运行以下命令启动 MCPHost：

    ```bash theme={null}
    mcphost --model ollama:qwen3
    ```

    或者，如果你想让它使用特定的配置文件：

    ```bash theme={null}
    mcphost --model ollama:qwen3 --config ~/.mcphost.json 
    ```

    <Warning>
      如果未提供 `--model`，MCPHost 会在环境变量中查找 `ANTHROPIC_API_KEY`，并使用 `anthropic:claude-sonnet-4-20250514` 模型。
    </Warning>

    我们将看到以下输出：

    ```text theme={null}
      ┃                                                                                     ┃
      ┃  Model loaded: ollama (qwen3)                                                       ┃
      ┃   MCPHost System (09:52)                                                            ┃
      ┃                                                                                     ┃

      ┃                                                                                     ┃
      ┃  Model loaded successfully on GPU                                                   ┃
      ┃   MCPHost System (09:52)                                                            ┃
      ┃                                                                                     ┃

      ┃                                                                                     ┃
      ┃  Loaded 3 tools from MCP servers                                                    ┃
      ┃   MCPHost System (09:52)                                                            ┃
      ┃                                                                                     ┃

      Enter your prompt (Type /help for commands, Ctrl+C to quit, ESC to cancel generation)
    ```

    我们可以使用 `/servers` 命令列出 MCP 服务器：

    ```text theme={null}
      ┃                                                                                      ┃
      ┃  ## Configured MCP servers                                                           ┃
      ┃                                                                                      ┃
      ┃  1. mcp-ch                                                                           ┃
      ┃   MCPHost System (10:00)                                                             ┃
      ┃
    ```

    以及运行 `/tools` 以列出可用工具：

    ```text theme={null}
      ┃  ## Available Tools                                                                  ┃
      ┃                                                                                      ┃
      ┃  1. mcp-ch__list_databases                                                           ┃
      ┃  2. mcp-ch__list_tables                                                              ┃
      ┃  3. mcp-ch__run_select_query
    ```

    然后，我们就可以就 ClickHouse SQL Playground 中可用的数据库/表向模型提问。

    根据我们的经验，使用较小的模型时 (默认的 qwen3 模型有 80 亿个参数) ，你需要更明确地说明希望它做什么。
    例如，你需要明确要求它列出数据库和表，而不是一开始就让它查询某个特定的表。
    你可以通过使用更大的模型 (例如 qwen3:14b) 在一定程度上缓解这个问题，但它在消费级硬件上的运行速度会更慢。
  </Step>
</Steps>