Jina AI MCP Tools

Jina AI MCP 工具

为编码 Agent 提供网页搜索和页面阅读。两个工具，不搞工具目录大杂烩。

jina-mcp-tools 是一个非官方且刻意保持精简的 Model Context Protocol（MCP） 服务，基于 Jina AI Reader and Search 构建。

它为 Codex、Claude Code 和其他编码 Agent 提供编程时通常需要的两项网页功能：

• 查找少量相关页面。
• 阅读真正重要的页面。

菜单就这么多。没有嵌入、截图、图片搜索、分类、重排序或 PDF 考古。这些都是实用工具，只是不一定适合每次编码时都带上。

说明

这是一个非官方社区项目，与 Jina AI 没有关联，也未获得其认可；它使用 Jina AI API，而非取而代之。

为什么还要做另一个 Jina 集成？

Jina 已经提供了出色的官方 MCP 服务和官方 CLI。它们旨在开放丰富的 Jina 功能。本项目做出了不同的取舍：它将上下文空间和工具选择所需的注意力视为值得节省的资源。

MCP 工具定义通常会在实际工作开始前进入 Agent 的上下文。需要时，丰富的工具目录很有价值；但对于日常编程研究来说，工具菜单可能比实际所需更丰富。jina-mcp-tools 最多提供两个专用工具，并采用一个刻意保持简单的工作流：

1. 搜索网页并获取简短的结果列表。
2. 选出有用的 URL。
3. 一次读取一个大小适中的页面。
4. 回到代码。

朴实无华的基础设施往往也最体贴。

应该使用哪种 Jina 集成？

	jina-mcp-tools	官方 Jina MCP	官方 Jina CLI
接口	通过 stdio/HTTP 运行的本地或可自托管 MCP	托管的远程 MCP	Shell 命令
默认范围	网页搜索和页面阅读	丰富的 Jina 工具目录	丰富的 Jina 命令套件
上下文方案	最多两个精简的工具定义	提供服务端工具筛选	使用 Agent 现有的 Shell 工具，并通过渐进式 --help 获取帮助
大型页面	基于 token 的显式分页和 LRU 缓存	根据客户端调整的响应保护机制	标准输出和 Unix 管道
最适合	希望使用精简原生 MCP 接口的编码 Agent	需要托管访问、研究工具、图片、PDF、嵌入或重排序的场景	希望使用管道、JSON、脚本和更完整 Jina 平台的 Agent 和用户

当原生 MCP 集成、精简的默认工具接口和分页阅读最重要时，选择 jina-mcp-tools。

需要托管端点或其更丰富的功能时，选择官方 MCP 服务。还可以通过 include_tools 或 include_tags 精简功能；如果托管方式的便利性比运行本地进程更重要，这是不错的选择。

如果 Agent 已能可靠地访问 Shell，且你希望使用 Unix 命令组合，或无需注册庞大的 MCP 工具目录就能使用完整的 Jina API 套件，则选择官方 CLI。

MCP 协议兼容性

同一服务通过 stdio 和 Streamable HTTP 同时支持当前的 MCP 2026-07-28 协议，以及基于旧式初始化流程的客户端。现代客户端可以使用 server/discover 和逐请求协议元数据；较旧的客户端则继续通过 SDK 的旧版兼容路径工作。

MCP 游标分页适用于 tools/list 和 resources/list 等发现操作。jina_reader 上的 page 参数属于独立的应用层内容分块机制：它可避免单个大型文档生成过大的 tools/call 结果，而 MCP 不会自动对这类结果分页。

快速开始

前置条件

• Node.js 20 或更高版本。
• 用于网页搜索的 Jina AI API 密钥。阅读工具无需密钥即可使用，但受 Jina 的未认证速率限制约束。

如果希望同时使用搜索和阅读功能，请在 shell 中设置 API 密钥：

export JINA_API_KEY=jina_your_api_key

Codex

codex mcp add jina-web --env JINA_API_KEY="$JINA_API_KEY" -- npx -y jina-mcp-tools

Claude Code

claude mcp add --scope user \
  --env JINA_API_KEY="$JINA_API_KEY" \
  --transport stdio jina-web -- npx -y jina-mcp-tools

在任一命令中省略 API 密钥选项，即可仅使用阅读功能。

VS Code

VS Code 将 MCP 配置存储在用户配置文件中的 mcp.json 或工作区级别的 .vscode/mcp.json 中。其配置使用 servers，而非 mcpServers。以下示例会安全地提示输入 API 密钥，并使用 VS Code 的输入变量支持来存储密钥：

{
  "inputs": [
    {
      "type": "promptString",
      "id": "jina-api-key",
      "description": "Jina AI API key",
      "password": true
    }
  ],
  "servers": {
    "jina-web": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "jina-mcp-tools"],
      "env": {
        "JINA_API_KEY": "${input:jina-api-key}"
      }
    }
  }
}

使用 MCP: Open User Configuration 打开用户配置，或将文件保存为 .vscode/mcp.json，以便与工作区共享服务配置。仅使用阅读功能时，请移除 env 和 inputs。

从命令行进行仅使用阅读功能的用户配置文件安装：

code --add-mcp "{\"name\":\"jina-web\",\"type\":\"stdio\",\"command\":\"npx\",\"args\":[\"-y\",\"jina-mcp-tools\"]}"

Claude Desktop、Cursor 和其他 MCP 客户端

对于使用 mcpServers JSON 格式的客户端：

{
  "mcpServers": {
    "jina-web": {
      "command": "npx",
      "args": [
        "-y",
        "jina-mcp-tools"
      ],
      "env": {
        "JINA_API_KEY": "your_jina_api_key_here"
      }
    }
  }
}

默认传输方式为 stdio。仅使用阅读功能时，请移除 env 块。

可用工具

jina_reader

提取并阅读网页内容。

参数：

• url — 要阅读的 URL（必填）。
• page — 分页内容的页码（默认值：1）。
• customTimeout — 超时时间覆盖值，单位为秒（可选）。

专为编码 Agent 研究设计：

• 自动对大型文档进行分页，而不是返回一个过大的响应。
• 使用 LRU 缓存，确保同一 URL 的后续页面可立即获取。
• 将指向分支、标签和提交的 GitHub 文件 URL 转换为原始内容 URL。
• 对维护中的文档和博客主机允许列表，先尝试直接通过 Accept: text/markdown 获取内容；如果响应失败或为空，则回退到 r.jina.ai。

默认缓存可存储 50 个 URL，每页限制约为 15,000 个 token。两项数值均可配置。

jina_search / jina_search_vip

搜索网页并返回简要候选结果。使用 jina_reader 获取有价值结果的完整内容。需要 Jina API 密钥。

根据 --search-endpoint，只会注册一种搜索工具：

• jina_search 使用 s.jina.ai（standard，默认值）。
• jina_search_vip 使用 svip.jina.ai（vip）。

参数：

• query — 搜索查询（必填）。
• count — 结果数量（默认值：5）。
• siteFilter — 将结果限制在某个域名内，例如 github.com。

默认结果数量较少是有意为之：先搜索，再选择性阅读，并为你最初正在处理的代码库留出一些上下文空间。

配置

Usage: jina-mcp-tools [options]

Options:
  --transport <stdio|http>         Transport type (default: stdio)
  --host <host>                    Host/interface in HTTP mode (default: 127.0.0.1)
  --port <1-65535>                 HTTP port (default: 3000)
  --tokens-per-page <positive-int> Tokens per reader page (default: 15000)
  --search-endpoint <standard|vip> Search endpoint (default: standard)
  --cache-size <positive-int>      Reader cache size in URLs (default: 50)
  -h, --help                       Show the built-in help

HTTP 传输

HTTP 模式适用于可自托管部署，或无法启动本地 stdio 进程的客户端。

启动服务：

# Search and reader
JINA_API_KEY=your_api_key npx -y jina-mcp-tools \
  --transport http \
  --host 127.0.0.1 \
  --port 3000

# Reader only
npx -y jina-mcp-tools --transport http --port 3000

连接到 http://localhost:3000/mcp：

• Codex：codex mcp add jina-web --url http://localhost:3000/mcp
• Claude Code：claude mcp add --transport http jina-web http://localhost:3000/mcp
• MCP Inspector：npx -y @modelcontextprotocol/inspector
• VS Code：code --add-mcp "{\"name\":\"jina-web\",\"type\":\"http\",\"url\":\"http://localhost:3000/mcp\"}"

HTTP 安全

HTTP 模式默认绑定到 127.0.0.1。对于远程部署，请将服务置于 TLS 之后，并要求使用 bearer 令牌：

JINA_MCP_HTTP_AUTH_TOKEN=change-me \
JINA_MCP_ALLOWED_HOSTS=mcp.example.com \
  npx -y jina-mcp-tools --transport http --host 0.0.0.0 --port 3000

客户端必须发送：

Authorization: Bearer change-me

默认情况下，浏览器来源的请求仅限于 localhost。对于基于浏览器的远程客户端，请将 JINA_MCP_ALLOWED_ORIGINS 设置为以逗号分隔的完整来源允许列表，例如 https://app.example.com。

环回 HTTP 绑定会自动验证 Host 标头。绑定到 0.0.0.0 或 :: 时，请将 JINA_MCP_ALLOWED_HOSTS 设置为以逗号分隔的公开主机名列表（不含协议或端口），这些主机名是服务接受的主机名。这样可以保护端点，避免 DNS 重绑定和意外的代理主机名。

在本地运行 MCP 进程并不意味着 Jina 请求可以离线处理：搜索和大多数 reader 请求仍会调用 Jina AI 服务。部分列入允许列表的 Markdown 主机和 GitHub 文件 URL 可能会被直接获取。

代理环境变量

若要通过代理路由出站请求，请启用 Node 的代理环境支持并提供代理 URL：

NODE_USE_ENV_PROXY=1 \
HTTP_PROXY=http://127.0.0.1:7890 \
HTTPS_PROXY=http://127.0.0.1:7890 \
NO_PROXY=localhost,127.0.0.1,::1 \
npx -y jina-mcp-tools

对于使用 mcpServers 配置格式的 MCP 客户端，请包含相同的环境变量：

{
  "mcpServers": {
    "jina-web": {
      "command": "npx",
      "args": ["-y", "jina-mcp-tools"],
      "env": {
        "JINA_API_KEY": "your_jina_api_key_here",
        "NODE_USE_ENV_PROXY": "1",
        "HTTP_PROXY": "http://127.0.0.1:7890",
        "HTTPS_PROXY": "http://127.0.0.1:7890",
        "NO_PROXY": "localhost,127.0.0.1,::1"
      }
    }
  }
}

或者，使用 NODE_OPTIONS=--use-env-proxy 启动 Node。只有启用代理环境支持后，才会使用代理 URL。

开发与测试

运行 pnpm verify，对生产代码和测试代码进行类型检查、构建并运行所有测试。 单独运行已编译的 MCP 传输套件，请使用 pnpm test:e2e。该套件会在新旧协议协商模式下测试 stdio 和 HTTP，涵盖 reader/search 调用、分页、上游请求以及错误恢复，且无需真实 API 凭据。 运行 pnpm test:live，通过导出的 JINA_API_KEY，选择性地调用真实 Jina 服务。 有关测试覆盖范围、边界以及真实 Codex 客户端工作流，请参阅测试计划。有关模块边界以及开发和发布步骤，请参阅架构和贡献指南。

范围与非目标

本项目并不打算开放 Jina 的所有 API。如果你需要嵌入、重排、分类、截图、图像或学术搜索、查询扩展、去重或结构化 PDF 提取，本项目并不适合。对于这些任务，请使用官方 MCP 服务或 CLI。

功能的关键就在于范围精简。如果这个服务增加二十个工具，还配上一个小型驾驶舱，那就说明出了大问题。

许可证

MIT

链接

• GitHub：github.com/PsychArch/jina-mcp-tools
• 问题反馈：github.com/PsychArch/jina-mcp-tools/issues