> For the complete documentation index, see [llms.txt](https://unsloth.ai/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://unsloth.ai/docs/zh/ji-chu/mcp.md).

# 如何在本地 LLM 中使用 MCP 服务器

这份分步指南向你展示如何连接 **模型上下文协议（MCP）** 服务器到本地 LLM，例如 [Qwen](/docs/zh/mo-xing/qwen3.6.md) 或 [Gemma](/docs/zh/mo-xing/gemma-4.md)，因此你运行的任何模型都可以通过 MCP 调用外部工具和服务。 将 MCP 连接到本地模型后，它就能安全地使用你的本地文件、应用、数据库和工具，而不只是基于记忆聊天，从而构建一个更有用、更私密、也可替换的 AI 助手，能够在你的真实环境中执行操作。

我们将使用开源仓库 [Unsloth](https://github.com/unslothai/unsloth) 和 [llama.cpp](#llama.cpp-guide) ，因为它们是本地模型推理/部署的热门框架。MCP 适用于本地 GGUF 模型和云端 [提供商模型](/docs/zh/ji-cheng/connections.md). **我们还会展示如何使用** [**多个 MCP 服务器**](#using-multiple-mcp-servers) **。**

MCP 工具可与其他模型能力一起工作，例如 [代码执行](/docs/zh/xin-zeng/studio/chat.md#code-execution) 和 [网页搜索](/docs/zh/xin-zeng/studio/chat.md#advanced-web-search)，因此单个模型可以在同一轮对话中搜索网页、运行代码，并调用你连接的服务。

### 使用场景

一旦连接了 MCP 服务器，你就可以让本地模型执行许多自动化任务。下面是一些例子：

* **搜索文档：** “找到相关文档并总结设置步骤。” - 可使用 Context7。
* **分析代码库：** “梳理这个仓库，并解释认证、计费和数据访问分别在哪里发生。” - 可使用 GitHub 官方 MCP 和 GitMCP 来分析仓库。
* **使用嵌入搜索网页** - 可使用 Exa 的 MCP 服务器进行带上下文嵌入支持的语义网页搜索。
* **调试网站 UI** - 可使用 Playwright 和 Chrome DevTools MCP 服务器来驱动网站并查找问题修复。

### 快速开始

我们将使用两种方式把你设备上的本地模型连接到 MCP 服务器。两种方式都使用开源包： [Unsloth](https://github.com/unslothai/unsloth) 和 [llama.cpp](llama.cpphttps://github.com/ggml-org/llama.cpp) 用于运行、提供服务并部署你的模型。

<a href="/pages/10191e6f82adfd362724184fd4ff98deb38d6ee5#unsloth-guide" class="button primary">Unsloth MCP 指南</a><a href="/pages/10191e6f82adfd362724184fd4ff98deb38d6ee5#llama.cpp-guide" class="button primary">Llama.cpp MCP 指南</a>

### 🦥 Unsloth 指南

在这个示例中，我们将使用 Unsloth 将任意本地模型连接到 MCP 服务器，例如 [Qwen3.6](/docs/zh/mo-xing/qwen3.6.md) 或 [Gemma 4](/docs/zh/mo-xing/gemma-4.md) 以及以下 MCP 服务器： [Vercel](https://mcp.vercel.com), [Context7](https://context7.com/), [Exa](https://exa.ai/) 和 [Hugging Face](https://huggingface.co/docs/hub/en/agents-mcp)。然后我们会问模型它能用这些做什么。相同步骤适用于任何 MCP 服务器。

{% stepper %}
{% step %}

#### 设置 Unsloth Studio

现在我们需要安装并设置 [Unsloth](/docs/zh/xin-zeng/studio.md)，这将使你能够在 UI 界面中运行云端模型。 [请看这里](/docs/zh/xin-zeng/studio/install.md) 以获取更详细的说明。

{% tabs %}
{% tab title="MacOS" %}

#### 步骤 1：设置 Unsloth

打开 `终端` ，然后输入下面的命令来安装 Unsloth。

```bash
curl -fsSL https://unsloth.ai/install.sh | sh
```

环境和所需包现在将开始安装。提示出现时输入 `Y` 并按回车继续。设置完成后，服务器将可在本地端口上使用 `8888`.

<figure><img src="/files/5f519c6be67e8e04d146b8890e77a97ea1d57b24" alt="" width="375"><figcaption></figcaption></figure>

{% hint style="info" %}
如果你在安装时跳过了启动应用，也可以稍后使用 `unsloth studio -p 8888`启动它。若要允许网络中其他设备连接，请改用 `unsloth studio -H 0.0.0.0 -p 8888` 。
{% endhint %}

#### 步骤 2：启动 Unsloth

打开你常用的浏览器并输入 `http://127.0.0.1:8888`  到地址栏中。如果这是你第一次安装 Unsloth，你会被转到密码页面，需要创建一个新密码。随后你应该会看到如下所示的聊天页面。
{% endtab %}

{% tab title="Windows" %}

#### 步骤 1：设置 Unsloth

打开开始菜单，搜索 `PowerShell`，然后启动它。复制并输入安装命令：

```powershell
irm https://unsloth.ai/install.ps1 | iex
```

它将自动开始安装。安装完成后，PowerShell 会询问你是否要启动 Unsloth Studi&#x6F;**.**

<figure><img src="/files/5f519c6be67e8e04d146b8890e77a97ea1d57b24" alt="" width="375"><figcaption></figcaption></figure>

你也可以使用以下命令启动它：

```bash
unsloth studio -H 0.0.0.0 -p 8888
```

{% hint style="info" %}
如果你希望该实例可被 PC/计算机之外的客户端访问，\
请添加 `-H 0.0.0.0` 到 `unsloth studio` 命令中。
{% endhint %}

#### 步骤 2：启动 Unsloth

在 `http://127.0.0.1:8888` 浏览器中打开。首次启动时，创建一个新密码以继续进入聊天页面。 **Unsloth Studio** 现已安装并可使用。
{% endtab %}

{% tab title="Linux, WSL" %}

#### 步骤 1：设置 Unsloth

{% tabs %}
{% tab title="Linux" %}
打开你的终端应用程序。你可以通过按 `Ctrl + Alt + T`来启动它，或者搜索 `Terminal` ，在系统应用菜单中找到它。
{% endtab %}

{% tab title="WSL" %}
点击 Windows 开始菜单，输入你已安装发行版的名称（例如 `Ubuntu`），然后打开它。

{% hint style="warning" %}
在 **WSL**，确保你的 **NVIDIA 驱动** 已安装在 **Windows** 上（不是在 WSL 内），并且 **CUDA 工具包** 已安装在你的 WSL 发行版中。详情请参见下面的系统要求。
{% endhint %}
{% endtab %}
{% endtabs %}

要安装，请复制并运行安装命令：

```bash
curl -fsSL https://unsloth.ai/install.sh | sh
```

然后：

1. 点击终端窗口内
2. 使用 `Ctrl + Shift + V`
3. 按 `回车`

Unsloth 将开始设置环境并安装所需包，如下所示。在询问你是否允许 Studio 现在启动时，输入 **Y** 并按 `回车` 。这将会在你的本地 **8888** 端口上启动 Unsloth。

<figure><img src="/files/6f5baa1b6cb53a7720aa0f8a23166f0ba32cb456" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
如果你在安装过程中选择不启动 Unsloth，也可以随时使用 `unsloth studio -p 8888` 来启动 Unsloth 应用。如果你希望你的 Unsloth 实例可被 PC/计算机之外的客户端访问，请添加 `-H 0.0.0.0` 到 `unsloth studio` 命令中。
{% endhint %}

#### 步骤 2：启动 Unsloth

打开你常用的浏览器并输入 `http://127.0.0.1:8888`  到地址栏中。如果这是你第一次安装 Unsloth，你会被转到密码页面，需要创建一个新密码。之后，Unsloth 应该会按下方所示在聊天页面打开。
{% endtab %}
{% endtabs %}
{% endstep %}

{% step %}

#### **启用 MCP**

点击聊天工具栏中的“MCP”。

<figure><img src="/files/f54d02b96e5a89fc26d4977e7615212f99f04a78" alt=""><figcaption></figcaption></figure>

Unsloth Studio 默认支持 Context7、Exa 和 Hugging Face 的 MCP。开启 Exa [网页搜索](/docs/zh/xin-zeng/studio/chat.md#advanced-web-search) 将会禁用我们现有的默认搜索工具。
{% endstep %}

{% step %}

#### **添加自定义 MCP 服务器**

要添加 Vercel MCP 服务器，点击“Add custom MCP”，你会看到一个弹出窗口：

<figure><img src="/files/5e55d90627e7b613dfbab32d3156e8109734ad2e" alt=""><figcaption></figcaption></figure>

填写服务器详细信息：

1. **显示名称**：一个友好的标签，例如 `Vercel`.
2. **URL**：服务器的基础端点，例如 `https://mcp.vercel.com`.
3. 请在下面选择一种认证方式。

{% tabs %}
{% tab title="OAuth 登录" %}
对于需要基于浏览器认证的服务器（GitHub、Linear、Vercel 等），请开启 **使用 OAuth 登录**。首次连接时会打开浏览器窗口，以便你授权 Unsloth。
{% endtab %}

{% tab title="自定义请求头" %}
对于使用令牌认证的服务器，请关闭 OAuth，然后点击 **添加请求头** 在 **自定义请求头**下方。添加一个 `Authorization` 请求头，并填入你的令牌：

```
Authorization: Bearer <your-token>
```

{% endtab %}
{% endtabs %}

<figure><img src="/files/6ed763197a92fb004556b9d2b20f0cb4d561fced" alt="" width="563"><figcaption></figcaption></figure>
{% endstep %}

{% step %}

#### **测试并添加**

点击 **测试连接** 以确认 Unsloth 能访问该服务器。一旦成功，点击 **添加服务器** 保存它。

如果 **测试连接** 失败，请检查 URL 是否是服务器的基础端点（不是文档页面），以及你的认证方式是否正确。请参见下面的故障排除。

<figure><img src="/files/b5e101551610993b0a28e50e3231f978a95a91dc" alt="" width="563"><figcaption></figcaption></figure>
{% endstep %}

{% step %}

#### **验证已加载的工具**

服务器现在会出现在 MCP 服务器列表中。Unsloth 会自动获取它的工具并显示确认信息，例如 *已刷新“Vercel”（18 个工具）*.

每个服务器都有控制项，可用于 **切换** 其开/关、 **刷新** 其工具、 **编辑** 它，或 **删除** 它。请确保服务器的开关和 **使用 MCP 服务器** 总开关都已开启，然后关闭对话框。

如果启用，它会被高亮显示。你也可以再次点击它们来禁用。

<figure><img src="/files/92e6e66e9682e175a0ed7e03a46596def5307e37" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

#### **在聊天中使用它**

从 **选择模型** 下拉菜单中挑选任意模型并开始聊天。当你的请求需要时，模型现在可以自行调用服务器工具。

上面，一个本地 `gemma-4-E2B-it-GGUF` 被询问 *“你能使用 Vercel MCP 服务器吗？”* 并报告了它可以执行的操作：管理项目、分析日志、列出团队、生成访问链接、检查域名以及搜索 Vercel 文档。

<figure><img src="/files/74e253db65f329d2264e6593fa221d4fa06127d5" alt=""><figcaption></figcaption></figure>
{% endstep %}
{% endstepper %}

#### 使用多个 MCP 服务器

如果调用 3 个左右的多个 MCP 服务器会怎么样？我们将使用 Unsloth Studio 默认提供的 Exa、Context7 和 Hugging Face MCP 服务器，并全部启用。

如果你问“Unsloth 是否支持 Qwen 微调”，Exa 会提供非常详细的信息：

<figure><img src="/files/633be97c1169211319990c600a4a1c3578487157" alt=""><figcaption></figcaption></figure>

然后继续追问“搜索 Unsloth 文档了解如何执行这个操作”，这时会使用 Context7 来查找文档：

<figure><img src="/files/d7c618bc019317b6044daea5e52d2778a19cc931" alt=""><figcaption></figcaption></figure>

然后输入“搜索 Hugging Face 上的 unsloth/Qwen 模型”，Hugging Face 的 MCP 服务器就会被调用：

<figure><img src="/files/4e4a269fe106e38a1e5a0bca73360373745673e0" alt=""><figcaption></figcaption></figure>

#### 另一个具体使用场景示例

一旦服务器连接成功，就可以用自然语言让模型做实际工作。以下是使用 Vercel 服务器的一些示例：

* **调试失败的构建**: *“获取我最近一次部署的构建日志，并告诉我它为什么失败。”*
* **检查部署状态**: *“列出我最近的部署及其状态。”*
* **搜索文档**: *“在 Vercel 文档中搜索如何设置自定义域名。”*
* **域名调研**: *“ `myproject.dev` 可用吗，费用大概是多少？”*

### 🦙 Llama.cpp 指南

{% stepper %}
{% step %}

#### 安装或构建 llama.cpp

**macOS：**

```bash
brew install llama.cpp
```

或者对于 **Linux, Windows, WSL** 从源代码构建：

```bash
git clone https://github.com/ggml-org/llama.cpp
cmake -S llama.cpp -B llama.cpp/build -DCMAKE_BUILD_TYPE=Release
cmake --build llama.cpp/build --config Release -j --target llama-server llama-cli
```

{% endstep %}

{% step %}

#### 使用 GGUF 启动 llama-server

在这个示例中我们使用 [Gemma 4](/docs/zh/mo-xing/gemma-4.md) E4B GGUF：

```bash
llama-server \\
  -hf unsloth/gemma-4-E4B-it-GGUF:UD-Q4_K_XL \\
  --alias local \\
  --host 127.0.0.1 \\
  --port 8080 \\
  --no-ui \\
  --temp 1.0 \\
  --top-p 0.95 \\
  --top-k 64 \\
  --reasoning off
```

对于更大的 Gemma 4 26B-A4B 模型：

```bash
llama-server \\
  -hf unsloth/gemma-4-26B-A4B-it-GGUF:UD-Q4_K_M \\
  --alias local \\
  --host 127.0.0.1 \\
  --port 8080 \\
  --no-ui \\
  --temp 1.0 \\
  --top-p 0.95 \\
  --top-k 64 \\
  --reasoning off
```

如需更多推理参数调整，请参见我们的 [Gemma 4 指南](/docs/zh/mo-xing/gemma-4.md).

你可以测试服务器：

```bash
curl http://127.0.0.1:8080/v1/chat/completions \\
  -H "Content-Type: application/json" \\
  -H "Authorization: Bearer none" \\
  -d '{
    "model": "local",
    "messages": [{"role": "user", "content": "用一句话打个招呼。"}]
  }'
```

{% endstep %}

{% step %}

#### 创建一个 MCP 文件系统沙盒

```bash
mkdir -p ~/mcp-workspace
cd ~/mcp-workspace
pwd
```

复制绝对路径。为你的 MCP 主机创建一个单独的项目文件夹：

```bash
mkdir -p ~/llama-mcp
cd ~/llama-mcp
```

创建 `server_config.json`:

{% code expandable="true" %}

```json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/ABSOLUTE/PATH/TO/mcp-workspace"
      ],
      "env": {}
    }
  }
}
```

{% endcode %}

将路径替换为你的真实工作区路径。IBM 的 `mcp-cli` 文档使用相同的 `server_config.json` 结构和相同的 `npx -y @modelcontextprotocol/server-filesystem /path/to/allowed/files` 文件系统配置。
{% endstep %}

{% step %}

#### 针对 llama.cpp 运行终端 MCP 主机

使用 IBM 的 `mcp-cli`；它是一个带有聊天模式、工具发现以及自定义 OpenAI 兼容提供商支持的命令行 MCP 客户端/主机。其文档建议使用 `uvx mcp-cli --help`，支持项目 `server_config.json`，并通过 `--api-base` 和 `--api-key`.

`mcp-cli` 启动时需要配置文件。因此有必要增加一步来创建它。例如：

{% code title="" expandable="true" %}

```bash
mkdir -p ~/.chuk_llm
cat > ~/.chuk_llm/config.yaml <<'YAML'
openai_compatible:
  client_class: "chuk_llm.llm.providers.openai_client:OpenAILLMClient"
  default_model: "local"
  models: ["*"]
YAML
```

{% endcode %}

然后运行：

```bash
uvx mcp-cli \\
  --provider llamacpp \\
  --api-base http://127.0.0.1:8080/v1 \\
  --api-key none \\
  --model local \\
  --server filesystem \\
  --config-file server_config.json
```

然后尝试：

```
列出文件系统工作区中的文件。
```

然后：

```
创建一个只有一行问候语的 hello.txt，然后再读回它。
```

`mcp-cli` 默认启用了工具调用确认，因此你应该会在工具执行前看到提示。

**完整代码示例：**

{% code expandable="true" %}

```bash
# 终端 1
llama-server -hf unsloth/gemma-4-E4B-it-GGUF:UD-Q4_K_XL \\
  --alias local --host 127.0.0.1 --port 8080 --no-ui \\
  --temp 1.0 --top-p 0.95 --top-k 64 \\
  --chat-template-kwargs '{"enable_thinking":false}'

# 终端 2，位于包含 server_config.json 的文件夹中
uvx mcp-cli \\
  --provider llamacpp \\
  --api-base http://127.0.0.1:8080/v1 \\
  --api-key none \\
  --model local \\
  --server filesystem \\
  --config-file server_config.json
```

{% endcode %}
{% endstep %}
{% endstepper %}

### 故障排除

如果服务器连接失败或其工具没有出现，请检查 URL 是否是服务器的基础端点（例如 `https://mcp.vercel.com`），而不是文档页或控制面板页。对于 OAuth 服务器，请在浏览器登录窗口打开后完成登录；对于基于令牌的服务器，请验证 `Authorization` 请求头以及令牌是否有效。

点击 **刷新** 如果连接后工具没有显示出来，请刷新，并确保单独服务器开关和 **使用 MCP 服务器** 总开关都已开启。

### 安全说明

只连接你信任的 MCP 服务器。审查所请求的权限，并在读取私有数据、更改部署、购买域名或修改项目的操作中保持人工确认开启。尤其要注意将 MCP 服务器与网页搜索或其他工具结合使用，因为提示注入内容可能会尝试触发不需要的工具调用。

### 热门 MCP 服务器

以下是一些你可以连接的热门且实用的 MCP 服务器列表：

| MCP 服务器             | 最适合                   | 有用之处                                                                                                                               |
| ------------------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| **GitHub MCP**      | 仓库、问题、PR、代码搜索、Actions | 官方 GitHub MCP，支持远程和本地设置，涵盖仓库、问题、拉取请求、Actions、代码安全等。（[GitHub](https://github.com/github/github-mcp-server))                         |
| **Context7**        | 最新的库文档和示例             | 为编码助手拉取当前、特定版本的文档，而不是依赖过时的训练数据。使用 `https://mcp.context7.com/mcp`. ([GitHub](https://github.com/upstash/context7))                  |
| **Notion MCP**      | 文档、笔记、任务、项目知识         | 适合将 Notion 用于规格说明、PRD、路线图或笔记的团队。托管的 MCP 可以读取和写入工作区内容。（[Notion 开发者](https://developers.notion.com/guides/mcp/overview))             |
| **Slack MCP**       | 团队对话搜索                | 让 AI 工具查询 Slack 消息、频道、文件、线程和成员信息；具体操作取决于权限。（[Slack](https://slack.com/help/articles/48855576908307-Guide-to-the-Slack-MCP-server)) |
| **Linear MCP**      | 问题、项目、产品工作流           | 用于查找、创建和更新 Linear 问题、项目、评论及相关对象的官方远程 MCP。（[Linear](https://linear.app/changelog/2025-05-01-mcp))                                   |
| **Vercel MCP**      | 部署、日志、文档、域名           | 适用于前端/网页工作流：检查部署、日志、文档和项目上下文。请先检查客户端兼容性。（[Vercel](https://vercel.com/docs/agent-resources/vercel-mcp?utm_source=chatgpt.com))      |
| **Sentry MCP**      | 生产环境调试                | 帮助代理在有人参与的开发工作流中检查 Sentry 问题、跟踪、错误和性能数据。（[GitHub](https://github.com/getsentry/sentry-mcp))                                        |
| **文件系统 / 本地文件 MCP** | 本地项目文件                | 适用于本地 LLM 设置，通常通过 `stdio`。参考服务器最好仅视为示例或起点。（[GitHub](https://github.com/modelcontextprotocol/servers))                              |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://unsloth.ai/docs/zh/ji-chu/mcp.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.