Jina AI Remote MCP Server

CLI 版本

一个远程 Model Context Protocol (MCP) 服务器，提供对 Jina Reader、Embeddings 和 Reranker API 的访问，附带一套 URL 转 Markdown、网页搜索、图片搜索以及 embeddings/reranker 工具：

可选 *工具能免 API 密钥 使用，但存在速率限制。若要获得更高速率限制和更性能，请使用 Jina API 密钥，免费应用大全密钥请访问 https://jina.ai

用法

[!WARNING] 某些客户端不支持环境变量，因此您可能需要将下面的 ${JINA_API_KEY} 替换为硬编码的真实 API 密钥 jina_xxx。

[!NOTE] 服务使用 Streamable HTTP 传输，MCP 规范 2025-03-26。为兼容旧版，仍保留 /sse 端点作为别名。详见 FAQ。

对于支持远程 MCP 服务器的客户端：

{
  "mcpServers": {
    "jina-mcp-server": {
      "url": "https://mcp.jina.ai/v1",
      "headers": {
        "Authorization": "Bearer ${JINA_API_KEY}" // optional
      }
    }
  }
}

对于尚不支持远程 MCP 服务器的客户端，您需要一个本地代理 mcp-remote 来连接远程 MCP 服务器。

{
  "mcpServers": {
    "jina-mcp-server": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.jina.ai/v1",
        "--header",
        "Authorization: Bearer ${JINA_API_KEY}"
      ]
    }
  }
}

对于 Claude Code：

[!WARNING] 从 /sse 升级？ 如果您之前使用 --transport sse 添加，请先使用 claude mcp remove -s user jina 将其移除，然后使用重新下面的命令添加。

claude mcp add -s user --transport http jina https://mcp.jina.ai/v1 \
  --header "Authorization: Bearer ${JINA_API_KEY}"

对于 OpenAI Codex：找到 ~/.codex/config.toml，然后添加以下内容：

[mcp_servers.jina-mcp-server]
command = "npx"
args = [
    "-y",
    "mcp-remote",
    "https://mcp.jina.ai/v1",
    "--header",
    "Authorization: Bearer ${JINA_API_KEY}"]

Related MCP server: Sentinel Core Agent

注册前工具过滤

每个 MCP 工具都需要 LLM 在其上下文窗口中为工具名称、描述和模式分配额外的 token。对于上下文窗口有限的 LLM，在开始实际完成之前，通过提供所有 22 个其他工具，可以占用大量空间。

通过端点 URL（/v1?），在服务器端进行查询参数过滤，被排除的工具永不注册到 MCP 客户端。客户端和 LLM 永远看不到它们，从而将上下文窗口留给真正重要的内容。

查询参数

可用标签

优先级

过滤器按以下顺序应用（从高到低）：

1. exclude_tools - 始终排除指定的工具

2. exclude_tags - 排除指定标签中的工具

3. include_tools - 包含指定的工具

4. include_tags - 最初只包含指定标签中的工具

示例

排除并行搜索类工具（可节省 ~4 个工具所占的上下文 token）：

{
  "mcpServers": {
    "jina-mcp-server": {
      "url": "https://mcp.jina.ai/v1?exclude_tags=parallel",
      "headers": {
        "Authorization": "Bearer ${JINA_API_KEY}"
      }
    }
  }
}

仅包含搜索和读取工具：

{
  "mcpServers": {
    "jina-mcp-server": {
      "url": "https://mcp.jina.ai/v1?include_tags=search,read",
      "headers": {
        "Authorization": "Bearer ${JINA_API_KEY}"
      }
    }
  }
}

排除特定工具：

{
  "mcpServers": {
    "jina-mcp-server": {
      "url": "https://mcp.jina.ai/v1?exclude_tools=search_images,deduplicate_images",
      "headers": {
        "Authorization": "Bearer ${JINA_API_KEY}"
      }
    }
  }
}

故障排查

我陷入了工具调用循环，这是怎么回事？

这是 LMStudio 的一个常见问题：当默认上下文窗口为 4096，并且你使用 gpt-oss-120b 或 qwen3-4b-thinking 这类思考模型时。随着思考和工具不断调用，一旦达到了上下文窗口的上限，AI 就会慢慢丢失任务开头的信息，于是陷入了这个滚动的上下文窗口循环中。

解决办法是：加载模型时设置足够的上下文长度，以容纳整个工具调用链和思考过程。

我看不到所有工具。

部分 MCP 客户端有本地缓存，不会主动更新工具定义。如果你看不到可用的全部工具，或者工具看起来是旧的，你可能需要在 MCP 客户端配置中移除并重新添加 jina-mcp-server。这能强制客户端刷新其缓存的工具定义。在 LMStudio 中，你可以点击刷新按钮来加载新的工具。

Claude Desktop 在 Windows 上提示“Server disconnected”

Cursor 和 Claude Desktop（Windows）存在一个 bug，即在调用 npx 时不会对参数内的空格做转义，最终导致参数值被破坏。你可以用下面的方式来绕开这个问题：

{
  // rest of config...
  "args": [
    "mcp-remote",
    "https://mcp.jina.ai/v1",
    "--header",
    "Authorization:${AUTH_HEADER}" // note no spaces around ':'
  ],
  "env": {
    "AUTH_HEADER": "Bearer <JINA_API_KEY>" // spaces OK in env vars
  }
},

Cursor 在这台 MCP 服务上显示一个红点

这很可能是 Cursor 的 UI 显示 bug，但 MCP 本身工作正常，完全没问题。如果红点很碍眼，你可以开关一次来“重启”该 MCP（实际上，由于你是在把它当成远程 MCP 使用，所以并不是真正的“重启服务”，而主要是重启了本地代理）。

为什么我的 LLM 从不使用某些工具

如果你把全部工具都在 MCP 客户端里打开了，但 LLM 仍显示从不调用其中某些工具，或总是偏向某些工具而不是用另外一些，那这很常见——因为 LLM 在训练时只见过一组特定的工具。例如，我们很少见到 LLM 天然启用 parallel_* 这类工具，除非你明确要求它这样做。有研究指出，LLM 需要先用 parallel_* 工具训练过才用它。像 Qwen3-Next 这样的模型天生倾向于调用单例版本，却用带多个的数组查询来实现并行（目前我们的 MCP 也支持这种）。总之，在 Cursor 里，可以把下面这条规则加到你的 .mdc 文件里：

---
alwaysApply: true
---

When you are uncertain about knowledge, or the user doubts your answer, always use Jina MCP tools to search and read best practices and latest information. Use search_arxiv and read_url together when questions relate to theoretical deep learning or algorithm details. Use search_ssrn for social sciences, economics, law, and finance research. search_web, search_arxiv, and search_ssrn cannot be used alone - always combine with read_url or parallel_read_url to read from multiple sources. Remember: every search must be complemented with read_url to read the source URL content. For maximum efficiency, use parallel_* versions of search and read when necessary.

为什么我的内容被截断了？

Claude Code、Claude Desktop 和 Cursor 都会对 MCP 工具响应的内容设置 25k token 的固定上限。为了不让这些客户端把内容过大的响应整个拒绝掉，本服务会为 read_url 和 parallel_read_url 加上一个 token 保护护栏。

具体做法是：在放得下的前提下顺整保留各条内容，直到下一个放不下的条目为止——它会把它截成前缀，剩余内容被丢弃。接着会补一段简短的 [jina-mcp] ... 标注，说明被截断或丢失了哪些部分，让模型知道这只是一份不完整文档而不是完整内容。即使单条内容已经超出预算，也会保证保留至少一条内容。

该服务在配额上更偏向保守而不是恰好跑到上限，这是有必要的。因为服务端用 cl100k 计数 token，客户端则用自己的 tokenizer 计数 token；服务端只能按比例估算字符数来截断，客户端测量的却是序列化后的 JSON 载荷而不是纯文本。因此服务端在 token 预算上限之外，还要额外强制每个允许 token 对应 3 字节的硬性上限，这个限制与 tokenizer 无关——无论是 ASCII 文本（约 3.6 字节/token）还是中日韩 CJK 文本（约 3 字节/token）都一样。由于一旦响应被拒绝就什么也得不到，所以宁可低估低一些。

任何客户端都可以通过端点 URL 上的 max_tokens 参数设置自己的预算（例如 https://mcp.jina.ai/v1?max_tokens=50000），而 max_tokens=0 会完全关闭截断。对于其他本身支持配置限制上限的客户端（如 OpenAI Codex 的 tool_output_token_limit 参数），我们一般不去改接。

使用并行工具与带数组的单例工具

Claude Code 最近开始倾向用 parallel_*（如 parallel_search_web、parallel_read_url）这类工具做并行。然而，像 Qwen3-Next 这样的模型则更喜欢调用单例版本，然后通过数组一次传多个 query。两种方式都起作用：单例版（search_web、search_arxiv、search_ssrn、read_url）的 query/url 参数既接受单个字符串，也接受字符串数组。当传入数组时，这些工具会在内部自动并行执行所有查询，产生和显式并行调用 parallel_* 一样的并发效果。你可以用你的模型偏好那种风格就用那种。数组最多 5 个，与 parallel_* 工具所支持的条目上限相同。

为什么端点叫 /sse，却使用 Streamable HTTP？

/sse 端点保留下来了，是为了向后兼容老用户。目前推荐使用 /v1 端点。两者都用同一个 Streamable HTTP 传输（spec 2025-03-26 中新的 MCP 标准），而不是旧的、被废弃的 SSE 传输。

这种兼容是无缝的：

• Claude Desktop、Cursor、Windsurf 使用 mcp-remote，它默认采取 http-first 策略（先尝试 Streamable HTTP）

• Claude Code 原生同时支持两种传输方式

• LM Studio 也直接支持连接 Streamable HTTP 端点

响应的流式仍采用 SSE 格式（Content-Type: text/event-stream），但协议层面（会话管理、初始化）遵循 Streamable HTTP 规范。所有主流 MCP 客户端都兼容。

使用 mcp-remote 做客户端侧的工具过滤

如果你用 mcp-remote 作为本地代理，还可以借助 --ignore-tool 参数在客户端侧过滤工具：

{
  "mcpServers": {
    "jina-mcp-server": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.jina.ai/v1",
        "--header",
        "Authorization: Bearer ${JINA_API_KEY}",
        "--ignore-tool", "parallel_search_web",
        "--ignore-tool", "parallel_search_arxiv",
        "--ignore-tool", "parallel_read_url"
      ]
    }
  }
}

这种方案会在工具到达 MCP 客户端之前把它们挡在代理层。当然，用查询参数在服务端做过滤（见 工具过滤）会更高效，因为它从源头上就减少了 token 消耗。

带着问题去读页面

默认情况下 read_url 返回整页内容，模型为了回答一个问题要损耗掉页面上每个 token。如果传一个 question，则会把页面变成一个段落，再交给 Reranker v3.5 给段落打分，只返回排名最高的部分——这正好就是 search_web_deep 对它的结果页所采用的那条处理流程，只是你现在也可以把它套用于手头的 URL 上。

以上三个都是可选参数，question 是另两个生效的门开关，因此已有调用可以不改，按原样继续运运。

// full page: 13,713 bytes, 233 ms
{ "url": "https://jina.ai/news/what-late-chunking-really-is-and-what-its-not-part-ii/" }

// one passage: 756 bytes (5.5%), 569 ms
{ "url": "https://jina.ai/news/what-late-chunking-really-is-and-what-its-not-part-ii/",
  "question": "Which embedding models support late chunking?", "topk": 2 }

带 question 的响应会携带 question、snippets 和 snippet_source: content 字段，并 content 省略。如果抽取过程失败——可能page 为空、无法读取，或没有可排序的 API key——就会返回完整文本体，并在 snippet_source: full_content 上注明，同时有一条 note 说明原因，而不是用一个像模像样的排序回答夹带其中。

调整参数前有三点值得注意：

• 分数同时是一个置信度信号。 如果问的是页面并没有回答的内容，得分比真实命中的要低一个量级（实测：0.02 对 0.51–0.81）。排名虽然低，其实代表“这个页面没说”，而不是“排序失误”。

• 代码块和表格在排序前至少会被去掉。分块器会把它们和导航结构一起剥离，这样模板片段不会因为文本重合就能排到前面。代价是安装命令和参数表不适合拿来当段落搜索，所以*“如何安装 X”*不完全适合用这个模式问。

• 延迟大约比普通读取多一倍左右，因为段落提取会伴随着读取一起做，并且还要额外多一次句重排。只要任一条包含 question，parallel_read_url 就把它提低时上限给出到 60 秒。

如果你遇到瓶颈。不得不说这三条并不全面，更多做法可以继续阅读下面内容。

search_web 和 search_web_deep 的区别是什么？

search_web 只返回结果中的摘要正，大约 20 个词，往往是关键词台词，本身回答不了问题。search_web_deep 则更进一步，通过 Reader 读取每一页，并按句子边界切成一段约 100 词的切片，然后将所有页面的所有切片一次性放进同一个 Reranker 里做 listwise 排序，因此任意一页的切片都可能胜过其他页。snippet_source=auto（默认值）会把每个页的引擎摘要作为额外的候选，并 snippet_source 字段在每条结果中写明哪个赢了；content 则不参与 auto 流程，也没法看未读的页面，所以 content 设置下返回结果数可能比 num 少。

以下是从实时服务器上的各模式返回的前 5 条结果。摘要只保留首尾部分，中间用 (...n chars...) 表示并保留长度信息：

English —— what is the latest model from jina ai

中文 — jina ai 最新的模型是什么

• 引擎调用的代码片段有时是更好的答案。 英文 auto 搜索前三条结果返回为 serp —— 简短 而且第一条更直接回答了问题，而 content 则推 offer 了 jina.ai 首页导航。没有需要完整片段时，推荐使用 auto。

• 重排器只衡量相关性，不衡量新旧。 两次中文测试 deep 模式都把 2023 年的 jina-embeddings-v2 文章排在“询问最新模型”的第一位。用 tbs 限定区间，或检查每个结果的 date。

• 段落长度并不是统一的约 100 词。 导航指令密集的网页缺少分句标点，所以英文 content 的两条结果都扩展到了约 2000 个字符——已达单段限制。

开发指南

本地开发

# Clone the repository
git clone https://github.com/jina-ai/MCP.git
cd MCP

# Install dependencies
npm install

# Start development server
npm run start

部署到 Cloudflare Workers

这会把你的 MCP 服务器部署到类似于这样的 URL：jina-mcp-server.<your-account>.workers.dev/v1