> 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/studio/chat.md#code-execution) 和 [网页搜索](/docs/zh/xin/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 连接任意本地模型，例如 [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

最简单的入门方式是安装 [Unsloth Desktop](/docs/zh/desktop.md) 应用。它支持 [MacOS](/docs/zh/kuai-su-kai-shi/install/mac.md)、Linux、 [Windows](/docs/zh/kuai-su-kai-shi/install/windows-installation.md), [NVIDIA](/docs/zh/kuai-su-kai-shi/install/pip-install.md), [AMD](/docs/zh/kuai-su-kai-shi/install/amd.md)、Intel 和 CPU 配置。

<a href="https://unsloth.ai/download" class="button primary" data-icon="down-to-bracket">下载 Unsloth</a>

* <i class="fa-apple">:apple:</i> [下载 macOS 版本](https://unsloth.ai/download/mac)
* <i class="fa-windows">:windows:</i> [下载 Windows 版本](https://unsloth.ai/download/windows)
* <i class="fa-linux">:linux:</i> [下载 Linux 版本](https://unsloth.ai/download/linux)

或者，如果您偏好手动安装：

**MacOS、Linux、WSL：**

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

**Windows PowerShell：**

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

[请看这里](/docs/zh/desktop.md#get-started) 以获取详细说明。
{% endstep %}

{% step %}

#### **启用 MCP**

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

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

Unsloth Studio 默认支持 Context7、Exa 和 Hugging Face 的 MCP。开启 Exa [网页搜索](/docs/zh/xin/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 服务器，并启用全部 3 个。

如果你问“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 %}

#### 使用终端 MCP 主机连接 llama.cpp

使用 IBM 的 `mcp-cli`；它是一个命令行 MCP 客户端/主机，具有聊天模式、工具发现和自定义 OpenAI 兼容提供商支持。其文档推荐 `uvx mcp-cli --help`，支持项目 `server_config.json`，并通过以下方式支持运行时自定义 OpenAI 兼容提供商： `--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, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.