Kagi Search MCP：让 AI Agent 获得「人类级」搜索能力

想象这样一个场景：你正在用 AI 助手规划一次旅行，问它"2024年诺贝尔物理学奖得主的主要贡献是什么"。AI 可能会自信满满地给你一个看似合理但完全错误的答案——因为它训练数据有截止日期，无法获取最新信息。而如果你的 AI 助手接入了 Kagi Search MCP，它就能实时联网搜索，给你一个基于真实资料的准确回答。

这就是 Kagi Search MCP 的核心价值：它是一座桥，让 AI Agent 能够实时、精准地获取互联网上的最新信息。

为什么需要专门的搜索 MCP？

很多人会问：AI 模型不是已经很强大了吗，为什么还要接入外部搜索？这里有一个关键概念需要澄清：训练数据的时效性鸿沟（Temporal Knowledge Gap）。

即使是最先进的 GPT-4、Claude 或 Gemini，它们的知识都有截止日期。以 GPT-4 为例，其训练数据截止到 2023 年 12 月，这意味着它不知道 2024 年发生的任何事情。对于新闻查询、技术文档搜索、股票信息获取等场景，联网搜索能力是不可替代的。

更重要的是，Kagi Search 相比传统搜索引擎（如 Google、Bing）有本质区别：

隐私优先：Kagi 承诺不追踪用户行为，不卖用户数据，搜索记录不与广告主共享
AI 优化：Kagi 的搜索结果经过 LLM 预处理排序，更适合 AI 消费和理解
内容直通：Kagi Extract API 可以直接抓取并转换任意网页为干净的 Markdown，无需解析 HTML
语义搜索：基于向量嵌入的语义匹配，不是简单关键词匹配

Kagi Search 官方图标 Kagi Search 官方 Logo — 以隐私为中心的 AI 搜索引擎

什么是 MCP（Model Context Protocol）？

在深入 Kagi MCP 之前，有必要理解它所基于的协议。MCP（Model Context Protocol）是 Anthropic 在 2024 年底提出的开放标准，旨在解决一个长期困扰 AI Agent 开发的问题：每个 AI 工具都需要独立开发适配代码，导致生态碎片化。

打个比方：如果把 AI Agent 想象成一部手机，那么 MCP 就像是 USB-C 接口标准——它定义了 AI Agent 如何与各种外部工具（搜索、数据库、文件系统、API）进行标准化通信。有了 MCP 协议，开发者只需要实现一次 MCP Server，就能让 Claude、GPT-4、Codex 等所有支持 MCP 的 AI 客户端使用同一个工具。

Kagi Search MCP 就是 MCP 生态中的一个"搜索插件"。它的角色非常纯粹：封装 Kagi Search API 的能力，通过 MCP 协议暴露两个核心工具——kagi_search_fetch 和 kagi_extract。

核心技术架构

技术栈一览

组件	技术选型	说明
运行环境	Python 3.12	精确版本约束，避免兼容性问题
MCP 框架	FastMCP 3.2	基于 FastMCP 库实现 MCP Server
数据验证	Pydantic 2.12.5	类型安全的 API 请求/响应建模
HTTP 客户端	urllib3	带重试策略的连接池管理
认证	Bearer Token	MCP 协议标准认证方式
API 客户端	自动生成（OpenAPI Client）	基于 Kagi OpenAPI 规范生成

代码结构：清晰的双模块设计

项目源代码分为两个独立的 Python 包：

src/kagimcp/server.py — MCP Server 核心逻辑
- 定义两个 MCP 工具：kagi_search_fetch 和 kagi_extract
- 处理 MCP 协议层面的认证、参数验证、错误格式化
- 支持 stdio 和 HTTP 两种传输模式
- 内置 _KagiKeyPassthroughVerifier，支持 MCP 协议标准 Bearer Token 认证
src/openapi_client/ — Kagi API 客户端（自动生成）
- 基于 Kagi 官方 OpenAPI 规范自动生成
- 包含完整的类型模型：SearchRequest、ExtractRequest、ErrorEnvelope 等
- 所有 API 调用都经过 Pydantic 模型验证

认证机制：灵活的三层回退

server.py 中的 _resolve_api_key() 函数实现了优雅的认证降级策略：

# 优先级从高到低：
# 1. MCP 请求头中的 Authorization: Bearer <key>
# 2. 环境变量 KAGI_API_KEY
# 3. 抛出异常（无有效凭证）

这种设计确保了在不同的 MCP 客户端接入方式下都能正常工作：Claude Desktop 通过 JSON 配置注入环境变量，Codex CLI 通过 --env 参数传入，MCP 协议标准流程则通过请求头传递。

重试策略：生产级可靠性

urllib3 Retry 配置处理了 429（速率限制）和 5xx（服务端错误）的自动重试：

backoff_factor=0.5：指数退避，间隔 0.5s、1s、2s...
backoff_max=10.0：最大等待 10 秒
respect_retry_after_header：尊重服务端返回的 Retry-After 头
raise_on_status=False：非 2xx 响应不抛异常，由应用层处理

两种运行模式

MCP Server 支持两种传输模式：

模式	命令行参数	适用场景	通信方式
stdio 模式	无参数（默认）	Claude Desktop、Codex CLI	标准输入输出 JSON-RPC
HTTP 模式	`--http`	自建 AI 应用、独立服务	HTTP + SSE 流式响应

HTTP 模式下支持 CORS 配置，可通过 --cors-origins 参数指定允许的跨域来源，这对于构建 Web 应用集成的 AI 搜索功能非常有用。

核心工具详解

kagi_search_fetch：多模态搜索工具

这是项目的主打工具，支持五种搜索工作流（workflow）：

search（默认）：通用网页搜索，返回混合类别的 SERP 结果
news：新闻搜索，适合查询时事、最新报道
videos：视频内容搜索，可找教程、演讲等
podcasts：播客音频搜索
images：图片搜索

高级参数方面，Kagi Lens 是一个非常强大的功能。你可以理解为"专业化搜索过滤器"：

Lens ID 2（Academic）：仅搜索 .edu 学术域名
Lens ID 15（Programming）：仅搜索编程语言官方文档和论坛
Lens ID 29（News 360）：多角度全球新闻报道
Lens ID 120（Recipes）：高质量食谱网站
Lens ID 107（Small Web）：非商业化的小众网站

extract_count 参数允许在搜索结果中直接内联指定数量条目的完整页面内容（Markdown 格式），这对于需要深度内容的 AI 任务特别实用——一次搜索即可同时拿到摘要和全文。

kagi_extract：智能网页内容提取

这个工具使用 Kagi 的 Extract API，可以将任意网页转换为干净的 Markdown。它解决了 AI 处理网页内容时的常见痛点：

广告和追踪脚本清理：Kagi 自动移除页面噪音，保留核心内容
格式转换：将 HTML 转换为结构化的 Markdown，保留标题层级和代码块
隐私保护：通过 Kagi 服务器代理请求，隐藏原始请求来源

对于 AI Agent 来说，这个工具的价值在于：当搜索结果中的摘要不够时，可以直接提取完整页面内容进行深度阅读，无需自己处理 HTML 解析和内容清洗。

Kagi Search 仓库封面图 Kagi MCP 仓库在 GitHub 上的官方展示图

快速上手：从零到运行的完整指南

方式一：uvx 一键启动（推荐）

# 安装 uv（如果还没安装）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 安装 uv 后，一条命令运行
uvx kagimcp

uvx 是 Astral 公司（FastAPI/Ruff 的母公司）出品的 Python 包管理器，支持直接运行 PyPI 上的包，无需手动安装依赖。

方式二：Docker 部署

docker build -t kagimcp .
docker run -p 8000:8000 \
  -e KAGI_API_KEY=your_api_key \
  kagimcp

# 然后在 MCP 客户端中配置 HTTP 端点

Dockerfile 使用 python:3.12-slim 基础镜像，体积小（~150MB），通过 pip install kagimcp 安装包，暴露 8000 端口。

接入 Claude Desktop

打开 Claude Desktop 配置（Settings → Developer → Edit Config），添加：

{
  "mcpServers": {
    "kagi": {
      "command": "uvx",
      "args": ["kagimcp"],
      "env": {
        "KAGI_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

重启 Claude Desktop，即可在对话中使用 kagi_search_fetch 和 kagi_extract 工具。

适用场景与局限性

适合的场景

AI Agent 实时信息查询：Agent 需要回答时效性问题时调用搜索
技术文档自动化：自动搜索官方文档并提取内容
新闻舆情监控：定时搜索特定主题的最新报道
竞品分析：搜索特定产品/公司的最新动态和评测
学术研究辅助：使用 Academic Lens 搜索学术资源

需要注意的局限

Kagi API 是付费服务：虽然有免费额度，但生产使用需要订阅 Kagi。这与使用 Google Custom Search API 或 SerpAPI 类似，是商业化 API 的共同特点。
无 Web UI：Kagi MCP 是一个纯后端工具，没有图形界面。配置和调试需要通过修改 JSON 配置文件完成，对非技术用户有一定门槛。
Python 3.12 强制约束：pyproject.toml 中 requires-python = "==3.12.*"，无法在 3.11 或 3.13 上运行。如果你的环境是其他 Python 版本，必须通过 Docker 或 uv 隔离运行。
extract_count 有上限：最大值为 10，当需要同时提取大量页面内容时需要多次调用。

行业意义与生态定位

Kagi Search MCP 的出现，反映了 AI 应用架构的一个趋势：将外部工具能力标准化、MCP 化。

在此之前，每个 AI 应用如果想接入搜索能力，都需要单独开发：选择搜索 API（Google/Bing/SerpAPI/Kagi）→ 阅读该 API 的文档 → 编写认证和请求逻辑 → 处理响应和错误。这对个人开发者和小型团队来说成本很高。

MCP 协议+工具生态解决的就是这个问题。Kagi 团队只需要维护这一个 MCP Server，Claude Desktop 用户、Codex CLI 用户、OpenCode 用户都可以直接使用，不需要了解任何 Kagi API 的细节。这是 AI 工具生态走向标准化的重要信号。

从数据隐私角度看，Kagi 作为搜索后端的选择也有深意：与 Google（高度追踪）或 Bing（与 Microsoft 生态绑定）相比，Kagi 的隐私政策更加友好。对于企业级 AI 应用而言，搜索数据的处理方式也是一个合规考量因素。

总结

Kagi Search MCP 是一个定位清晰、技术扎实的小工具。它做的事情很简单：把 Kagi 搜索 API 的能力，通过 MCP 协议暴露给所有 AI Agent。

它的价值不在于功能多复杂，而在于填补了一个真实需求：让 AI 能实时、准确地获取互联网上的最新信息，而不是依赖于可能过时数年的训练数据。通过 MCP 协议的标准化封装，它降低了 AI 应用接入高质量搜索的门槛，让开发者可以专注于自己的核心业务逻辑。

对于正在构建 AI Agent、需要实时联网能力的开发者来说，这是一个值得关注和尝试的工具——尤其是当你对搜索结果的准确性和隐私性有较高要求时。

Kagi Search MCP：让 AI Agent 获得「人类级」搜索能力

这就是 Kagi Search MCP 的核心价值：它是一座桥，让 AI Agent 能够实时、精准地获取互联网上的最新信息。

为什么需要专门的搜索 MCP？

很多人会问：AI 模型不是已经很强大了吗，为什么还要接入外部搜索？这里有一个关键概念需要澄清：训练数据的时效性鸿沟（Temporal Knowledge Gap）。

更重要的是，Kagi Search 相比传统搜索引擎（如 Google、Bing）有本质区别：

隐私优先：Kagi 承诺不追踪用户行为，不卖用户数据，搜索记录不与广告主共享
AI 优化：Kagi 的搜索结果经过 LLM 预处理排序，更适合 AI 消费和理解
内容直通：Kagi Extract API 可以直接抓取并转换任意网页为干净的 Markdown，无需解析 HTML
语义搜索：基于向量嵌入的语义匹配，不是简单关键词匹配

Kagi Search 官方图标 Kagi Search 官方 Logo — 以隐私为中心的 AI 搜索引擎

什么是 MCP（Model Context Protocol）？

核心技术架构

技术栈一览

组件	技术选型	说明
运行环境	Python 3.12	精确版本约束，避免兼容性问题
MCP 框架	FastMCP 3.2	基于 FastMCP 库实现 MCP Server
数据验证	Pydantic 2.12.5	类型安全的 API 请求/响应建模
HTTP 客户端	urllib3	带重试策略的连接池管理
认证	Bearer Token	MCP 协议标准认证方式
API 客户端	自动生成（OpenAPI Client）	基于 Kagi OpenAPI 规范生成

代码结构：清晰的双模块设计

项目源代码分为两个独立的 Python 包：

src/kagimcp/server.py — MCP Server 核心逻辑
- 定义两个 MCP 工具：kagi_search_fetch 和 kagi_extract
- 处理 MCP 协议层面的认证、参数验证、错误格式化
- 支持 stdio 和 HTTP 两种传输模式
- 内置 _KagiKeyPassthroughVerifier，支持 MCP 协议标准 Bearer Token 认证
src/openapi_client/ — Kagi API 客户端（自动生成）
- 基于 Kagi 官方 OpenAPI 规范自动生成
- 包含完整的类型模型：SearchRequest、ExtractRequest、ErrorEnvelope 等
- 所有 API 调用都经过 Pydantic 模型验证

认证机制：灵活的三层回退

server.py 中的 _resolve_api_key() 函数实现了优雅的认证降级策略：

# 优先级从高到低：
# 1. MCP 请求头中的 Authorization: Bearer <key>
# 2. 环境变量 KAGI_API_KEY
# 3. 抛出异常（无有效凭证）

重试策略：生产级可靠性

urllib3 Retry 配置处理了 429（速率限制）和 5xx（服务端错误）的自动重试：

backoff_factor=0.5：指数退避，间隔 0.5s、1s、2s...
backoff_max=10.0：最大等待 10 秒
respect_retry_after_header：尊重服务端返回的 Retry-After 头
raise_on_status=False：非 2xx 响应不抛异常，由应用层处理

两种运行模式

MCP Server 支持两种传输模式：

模式	命令行参数	适用场景	通信方式
stdio 模式	无参数（默认）	Claude Desktop、Codex CLI	标准输入输出 JSON-RPC
HTTP 模式	`--http`	自建 AI 应用、独立服务	HTTP + SSE 流式响应

HTTP 模式下支持 CORS 配置，可通过 --cors-origins 参数指定允许的跨域来源，这对于构建 Web 应用集成的 AI 搜索功能非常有用。

核心工具详解

kagi_search_fetch：多模态搜索工具

这是项目的主打工具，支持五种搜索工作流（workflow）：

search（默认）：通用网页搜索，返回混合类别的 SERP 结果
news：新闻搜索，适合查询时事、最新报道
videos：视频内容搜索，可找教程、演讲等
podcasts：播客音频搜索
images：图片搜索

高级参数方面，Kagi Lens 是一个非常强大的功能。你可以理解为"专业化搜索过滤器"：

Lens ID 2（Academic）：仅搜索 .edu 学术域名
Lens ID 15（Programming）：仅搜索编程语言官方文档和论坛
Lens ID 29（News 360）：多角度全球新闻报道
Lens ID 120（Recipes）：高质量食谱网站
Lens ID 107（Small Web）：非商业化的小众网站

kagi_extract：智能网页内容提取

这个工具使用 Kagi 的 Extract API，可以将任意网页转换为干净的 Markdown。它解决了 AI 处理网页内容时的常见痛点：

广告和追踪脚本清理：Kagi 自动移除页面噪音，保留核心内容
格式转换：将 HTML 转换为结构化的 Markdown，保留标题层级和代码块
隐私保护：通过 Kagi 服务器代理请求，隐藏原始请求来源

Kagi Search 仓库封面图 Kagi MCP 仓库在 GitHub 上的官方展示图

快速上手：从零到运行的完整指南

方式一：uvx 一键启动（推荐）

# 安装 uv（如果还没安装）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 安装 uv 后，一条命令运行
uvx kagimcp

uvx 是 Astral 公司（FastAPI/Ruff 的母公司）出品的 Python 包管理器，支持直接运行 PyPI 上的包，无需手动安装依赖。

方式二：Docker 部署

docker build -t kagimcp .
docker run -p 8000:8000 \
  -e KAGI_API_KEY=your_api_key \
  kagimcp

# 然后在 MCP 客户端中配置 HTTP 端点

Dockerfile 使用 python:3.12-slim 基础镜像，体积小（~150MB），通过 pip install kagimcp 安装包，暴露 8000 端口。

接入 Claude Desktop

打开 Claude Desktop 配置（Settings → Developer → Edit Config），添加：

{
  "mcpServers": {
    "kagi": {
      "command": "uvx",
      "args": ["kagimcp"],
      "env": {
        "KAGI_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

重启 Claude Desktop，即可在对话中使用 kagi_search_fetch 和 kagi_extract 工具。

适用场景与局限性

适合的场景

AI Agent 实时信息查询：Agent 需要回答时效性问题时调用搜索
技术文档自动化：自动搜索官方文档并提取内容
新闻舆情监控：定时搜索特定主题的最新报道
竞品分析：搜索特定产品/公司的最新动态和评测
学术研究辅助：使用 Academic Lens 搜索学术资源

需要注意的局限

Kagi API 是付费服务：虽然有免费额度，但生产使用需要订阅 Kagi。这与使用 Google Custom Search API 或 SerpAPI 类似，是商业化 API 的共同特点。
无 Web UI：Kagi MCP 是一个纯后端工具，没有图形界面。配置和调试需要通过修改 JSON 配置文件完成，对非技术用户有一定门槛。
Python 3.12 强制约束：pyproject.toml 中 requires-python = "==3.12.*"，无法在 3.11 或 3.13 上运行。如果你的环境是其他 Python 版本，必须通过 Docker 或 uv 隔离运行。
extract_count 有上限：最大值为 10，当需要同时提取大量页面内容时需要多次调用。

行业意义与生态定位

Kagi Search MCP 的出现，反映了 AI 应用架构的一个趋势：将外部工具能力标准化、MCP 化。

总结

Kagi Search MCP 是一个定位清晰、技术扎实的小工具。它做的事情很简单：把 Kagi 搜索 API 的能力，通过 MCP 协议暴露给所有 AI Agent。

对于正在构建 AI Agent、需要实时联网能力的开发者来说，这是一个值得关注和尝试的工具——尤其是当你对搜索结果的准确性和隐私性有较高要求时。