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

# 使用 MCP 集成到 AI 助理

> 介绍如何使用 Linkly AI MCP，获得更高的灵活性和更极客的体验。

## MCP 介绍

MCP（Model Context Protocol）是一个开放协议，让 AI 助理能够调用外部工具获取上下文信息。Linkly AI Desktop 内置了 MCP 服务，安装后自动启动，无需额外配置。

你只需要将 Linkly AI 的 MCP 端点添加到你的 AI 助理中，AI 就能直接搜索、浏览和阅读你的本地文档。

## 三种访问模式

Linkly AI 提供三种 MCP 访问模式，适用于不同场景：

<CardGroup cols={3}>
  <Card title="本机访问" icon="computer" iconType="duotone">
    直接在本机 AI 工具中使用，无需任何额外配置。适用于 Claude Code、Cursor 等本地应用。

    端点：`http://127.0.0.1:60606/mcp`
  </Card>

  <Card title="局域网访问" icon="wifi" iconType="duotone">
    同一网络下的其他设备也可连接。需要开启局域网访问并使用访问令牌。

    端点：`http://{局域网IP}:60606/mcp`
  </Card>

  <Card title="远程访问（公网）" icon="globe" iconType="duotone" href="/zh/use-in-remote">
    通过隧道在公网远程访问。适用于 ChatGPT、Claude.ai 等在线 AI 应用。

    端点：`https://mcp.linkly.ai/mcp`
  </Card>
</CardGroup>

本页介绍本机访问和局域网访问的配置方法。如需远程访问（公网），请参阅[远程访问指南](/zh/use-in-remote)。

<CardGroup cols={2}>
  <Card title="HTTP MCP（推荐）" icon="globe" iconType="duotone">
    大多数 AI 助理支持 HTTP 传输协议，直接连接 Linkly AI 的 MCP 端点，无需安装
    CLI
  </Card>

  <Card title="Stdio MCP" icon="terminal" iconType="duotone">
    部分 AI 助理仅支持 stdio 传输协议，需要通过 Linkly AI CLI 作为桥接
  </Card>
</CardGroup>

<Tip>
  如果你不确定选哪种方式，选 HTTP MCP 即可。只有当你的 AI 助理明确不支持 HTTP
  传输时，才需要使用 Stdio 方式。
</Tip>

## 前提条件

<Steps>
  <Step title="安装并启动 Linkly AI Desktop">
    前往 [linkly.ai](https://linkly.ai/#download) 下载并安装桌面应用。首次启动后完成初始化向导，应用会自动开始索引你的文档。
  </Step>

  <Step title="确认 MCP 服务已启动">
    Linkly AI Desktop 启动后会自动运行 MCP 服务。你可以在应用设置中查看 MCP 服务的状态和端口号。

    默认 MCP 端点：`http://127.0.0.1:60606/mcp`
  </Step>
</Steps>

<Note>
  如果你选择 Stdio MCP 方式，还需要额外[安装 Linkly AI CLI](./use-cli)。
</Note>

## 使用方法

### HTTP MCP（推荐）

适用于支持 HTTP/StreamableHTTP 传输协议的 AI 助理，无需安装 CLI，直接连接。

<Tabs>
  <Tab title="Claude Code" icon="terminal">
    在终端中运行：

    ```bash theme={null}
    claude mcp add --transport http linkly-ai http://127.0.0.1:60606/mcp
    ```
  </Tab>

  <Tab title="Cursor" icon="code">
    1. 打开 Settings → MCP Servers → Add Server
    2. Name: `linkly-ai`
    3. Type: `StreamableHTTP`
    4. URL: `http://127.0.0.1:60606/mcp`
  </Tab>

  <Tab title="Codex" icon="robot">
    在终端中运行：

    ```bash theme={null}
    codex mcp add linkly-ai --url http://127.0.0.1:60606/mcp
    ```
  </Tab>

  <Tab title="Cherry Studio" icon="star">
    1. 打开 Settings → MCP Servers → Add
    2. Name: `linkly-ai`
    3. Type: `StreamableHTTP`
    4. URL: `http://127.0.0.1:60606/mcp`
  </Tab>
</Tabs>

<Tip>
  其中 `60606` 为 Linkly AI 的 MCP
  服务默认端口号，如果无法连接可在应用设置中查看实际端口号。
</Tip>

### Stdio MCP

适用于支持 stdio 传输协议的 AI 助理。需要先[安装 Linkly AI CLI](./use-cli#安装)，然后将 `linkly mcp` 作为 stdio 桥接命令配置到 AI 助理中。

<Tabs>
  <Tab title="Claude Code" icon="terminal">
    在终端中运行：

    ```bash theme={null}
    claude mcp add linkly-ai -- linkly mcp
    ```
  </Tab>

  <Tab title="Codex" icon="robot">
    在终端中运行：

    ```bash theme={null}
    codex mcp add linkly-ai -- linkly mcp
    ```
  </Tab>

  <Tab title="Cherry Studio" icon="star">
    1. 打开 Settings → MCP Servers → Add
    2. Name: `linkly-ai`
    3. Type: `stdio`
    4. Command: `linkly`
    5. Args: `mcp`
  </Tab>

  <Tab title="其他 AI 助理" icon="puzzle-piece">
    对于其他支持 stdio MCP 的 AI 助理，将以下命令配置为 MCP 服务器即可：

    * 命令: `linkly`
    * 参数: `mcp`

    CLI 会自动发现本地运行的 Linkly AI Desktop 并建立连接。
  </Tab>
</Tabs>

### 局域网访问

如果你需要从同一网络下的其他设备（如另一台电脑、NAS 上的 n8n 等）访问 Linkly AI，可以开启局域网访问模式。

<Steps>
  <Step title="开启局域网访问">
    在 Linkly AI Desktop 中，进入 **设置 → MCP**，找到「局域网访问」区域，开启开关。
  </Step>

  <Step title="获取局域网 URL 和访问令牌">
    开启后，界面会显示：

    * **局域网 URL**：类似 `http://192.168.x.x:60606/mcp`
    * **访问令牌**：一串随机字符串

    将这两个信息复制到需要连接的设备上。
  </Step>

  <Step title="在其他设备上配置">
    在其他设备的 AI 工具中添加 MCP 服务器时，使用局域网 URL 作为端点，并在请求头中携带访问令牌：

    ```
    Authorization: Bearer <你的访问令牌>
    ```

    如果使用 Linkly AI CLI，可以这样连接：

    ```bash theme={null}
    linkly search "关键词" --endpoint http://192.168.x.x:60606/mcp --token <你的访问令牌>
    ```
  </Step>
</Steps>

<Warning>
  局域网访问使用 HTTP 明文传输，仅建议在家庭等可信网络中使用。请勿在公共 WiFi
  或不受信任的网络环境中开启此功能。
</Warning>

### 验证集成

配置完成后，你可以在 AI 助理中发送以下提示词来验证：

<Prompt description="搜索我的文档中关于 XX 的内容">
  搜索我的文档中关于项目管理的内容
</Prompt>

如果集成成功，AI 助理会调用 Linkly AI 的 `search` 工具并返回你本地文档中的相关结果。

### 搭配 Skills 使用

我们强烈建议在配置 MCP 的同时[安装 Linkly AI Skills](./use-skills)。Skills 教会 AI 助理如何高效地使用 Linkly AI 的工具，包括何时搜索、何时浏览大纲、何时阅读全文，以及如何处理长文档的分页阅读。

<Prompt description="请帮我安装 Agent Skill linkly-ai-skills， 并完成 LinklyAI 的工具集成...">
  请帮我安装 Agent Skill linkly-ai-skills， 并完成 LinklyAI
  的工具集成，参考：[https://linkly.ai/docs/zh/use-skills](https://linkly.ai/docs/zh/use-skills)
</Prompt>

## 参数说明

MCP 服务暴露七个工具，构成渐进式的文档访问工作流：

* `search` — 混合检索（BM25 + 向量），主入口
* `outline` — 文档大纲
* `grep` — 单文档内的正则匹配
* `read` — 按行阅读文档
* `list_libraries` — 列出可用知识库
* `explore` — 文档集合鸟瞰概览
* `find_paths` — 按关键词定位文件夹路径，给 `search` 的 `path_glob` 提供候选

每条成功响应都会附带一个 UTC 时间戳：Markdown 输出末尾的 `[meta] now=...` 行，或 JSON 输出顶层的 `_meta.now` 字段，可用于推算"上个月"等相对日期。错误响应不带这个元数据。

完整参数表、返回字段、响应元数据格式以及调用示例，请参考 [Linkly AI MCP 工具介绍](./tools-intro)。