Skip to content
Back to search

MCP

Official Jina AI Remote MCP Server

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/jina-ai/MCP with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/jina-ai/MCP'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/jina-ai--mcp/badge.svg)](/listings/jina-ai--mcp)

HTML

<a href="/listings/jina-ai--mcp"><img src="/api/listings/jina-ai--mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 411 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Jina AI Remote MCP Server
  2. A remote Model Context Protocol (MCP) server for the Jina Reader, Search, Embeddings and Reranker APIs:
  3. ## Usage
  4. > [!WARNING]
  5. > Some clients do not support env variable, so you may need to replace `${JINA_API_KEY}` below to a hardcoded real API key `jina_xxx`.
  6. For client that supports remote MCP server:
  7. ```json
  8. {
  9. "mcpServers": {
  10. "jina-mcp-server": {
  11. "url": "https://mcp.jina.ai/v1",
  12. "headers": {
  13. "Authorization": "Bearer ${JINA_API_KEY}" // optional
  14. }
  15. }
  16. }
  17. }
  18. ```
  19. For Claude Code:
  20. ```bash
  21. claude mcp add -s user --transport http jina https://mcp.jina.ai/v1 \
  22. --header "Authorization: Bearer ${JINA_API_KEY}"
  23. ```
  24. For OpenAI Codex: find `~/.codex/config.toml` and add the following:
  25. ```toml
  26. [mcp_servers.jina-mcp-server]
  27. command = "npx"
  28. args = [
  29. "-y",
  30. "mcp-remote",
  31. "https://mcp.jina.ai/v1",
  32. "--header",
  33. "Authorization: Bearer ${JINA_API_KEY}"]
  34. ```
  35. For client that does not support remote MCP server yet, you need [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) a local proxy to connect to the remote MCP server.
  36. ```json
  37. {
  38. "mcpServers": {
  39. "jina-mcp-server": {
  40. "command": "npx",
  41. "args": [
  42. "mcp-remote",
  43. "https://mcp.jina.ai/v1",
  44. "--header",
  45. "Authorization: Bearer ${JINA_API_KEY}"
  46. ]
  47. }
  48. }
  49. }
  50. ```
  51. ## Available tools
  52. | Tool | Description | Is Jina API Key Required? |
  53. |-----------|-------------|----------------------|
  54. | `primer` | Get current contextual information for localized, time-aware responses | No |
  55. | `read_url` | Read a web page or PDF as markdown. Pass `question` for passages instead of the full body via [Reader API](https://jina.ai/reader) | Optional* |
  56. | `capture_screenshot_url` | Capture a screenshot of a web page via [Reader API](https://jina.ai/reader) | Optional* |
  57. | `guess_datetime_url` | Guess a page's publish or last-update datetime, with a confidence score | No |
  58. | `search_web` | Search the web. Returns titles, URLs and engine snippets via [Reader API](https://jina.ai/reader) | Yes |
  59. | `search_arxiv` | Search academic papers and preprints on arXiv repository via [Reader API](https://jina.ai/reader) | Yes |
  60. | `search_ssrn` | Search academic papers on SSRN (Social Science Research Network) via [Reader API](https://jina.ai/reader) | Yes |
  61. | `search_images` | Search the web for images via [Reader API](https://jina.ai/reader) | Yes |
  62. | `search_jina_blog` | Search Jina AI news and blog posts at [jina.ai/news](https://jina.ai/news) | No |
  63. | `sort_by_relevance` | Rerank documents by relevance to a query via [Reranker API](https://jina.ai/reranker) | Yes |
  64. | `deduplicate_strings` | Get top-k semantically unique strings via [Embeddings API](https://jina.ai/embeddings) and [submodular optimization](https://jina.ai/news/submodular-optimization-for-diverse-query-generation-in-deepresearch) | Yes |
  65. | `extract_pdf` | Extract figures, tables, and equations from PDF documents using layout detection. Takes an arXiv id, or a PDF URL on arxiv.org, ssrn.com, openreview.net or aclanthology.org | Yes |
  66. > Optional tools work without an API key at [rate limits](https://jina.ai/api-dashboard/rate-limit). Use a key for higher limits. Free keys: [https://jina.ai](https://jina.ai)
  67. ## Tool Filtering before Registering
  68. Registering a tool costs context tokens for its name, description and schema whether or not it is called. With 12 tools, that budget is spent before the first request.
  69. Filtering server-side through query parameters on the endpoint URL (`/v1?...`) excludes tools before registration, so the client never sees them.
  70. ### Query Parameters
  71. | Parameter | Description | Example |
  72. |-----------|-------------|---------|
  73. | `exclude_tools` | Comma-separated tool names to exclude | `exclude_tools=search_web,search_arxiv` |
  74. | `include_tools` | Comma-separated tool names to include | `include_tools=read_url,search_web` |
  75. | `exclude_tags` | Comma-separated tags to exclude | `exclude_tags=search,rerank` |
  76. | `include_tags` | Comma-separated tags to include | `include_tags=search,read` |
  77. | `max_tokens` | Cap `read_url` response size in tokens. `0` disables truncation | `max_tokens=50000` |
  78. ### Available Tags
  79. | Tag | Tools |
  80. |-----|-------|
  81. | `search` | search_web, search_arxiv, search_ssrn, search_images, search_jina_blog |
  82. | `read` | read_url, capture_screenshot_url |
  83. | `utility` | primer, guess_datetime_url, extract_pdf |
  84. | `rerank` | sort_by_relevance, deduplicate_strings |
  85. ### Precedence
  86. Filters are applied in this order (highest to lowest priority):
  87. 1. `exclude_tools` - Always excludes specified tools
  88. 2. `exclude_tags` - Excludes tools in specified tags
  89. 3. `include_tools` - Includes specified tools
  90. 4. `include_tags` - Starts with only tools in specified tags
  91. ### Examples
  92. Exclude the rerank and utility tags:
  93. ```json
  94. {
  95. "mcpServers": {
  96. "jina-mcp-server": {
  97. "url": "https://mcp.jina.ai/v1?exclude_tags=rerank,utility",
  98. "headers": {
  99. "Authorization": "Bearer ${JINA_API_KEY}"
  100. }
  101. }
  102. }
  103. }
  104. ```
  105. Only include search and read tools:
  106. ```json
  107. {
  108. "mcpServers": {
  109. "jina-mcp-server": {
  110. "url": "https://mcp.jina.ai/v1?include_tags=search,read",
  111. "headers": {
  112. "Authorization": "Bearer ${JINA_API_KEY}"
  113. }
  114. }
  115. }
  116. }
  117. ```
  118. Exclude specific tools:
  119. ```json
  120. {
  121. "mcpServers": {
  122. "jina-mcp-server": {
  123. "url": "https://mcp.jina.ai/v1?exclude_tools=search_ssrn,search_images",
  124. "headers": {
  125. "Authorization": "Bearer ${JINA_API_KEY}"
  126. }
  127. }
  128. }
  129. }
  130. ```
  131. ## Troubleshooting
  132. ### I got stuck in a tool calling loop - what happened?
  133. This is a common issue with LMStudio when the default context window is 4096 and you're using a thinking model like `gpt-oss-120b` or `qwen3-4b-thinking`. As thinking and tool calling continue, the run hits the context limit, the model loses the start of the task, and it loops.
  134. Load the model with enough context length to hold the whole tool-calling chain.
  135. ![set long enough context](/.readme/image.png)
  136. ### I can't see all tools.
  137. Some MCP clients have local caching and do not actively update tool definitions. If tools are missing or look outdated, remove and re-add the jina-mcp-server to force a refresh of the cached definitions. In LMStudio, you can click the refresh button to load new tools.
  138. ![update local mcp clients](/.readme/image2.png)
  139. ### Claude Desktop says "Server disconnected" on Windows
  140. Cursor and Claude Desktop (Windows) [have a bug](https://www.npmjs.com/package/mcp-remote#:~:text=Note%3A%20Cursor,env%20vars%0A%20%20%7D%0A%7D%2C) where spaces inside args aren't escaped when it invokes npx, which ends up mangling these values. You can work around it using:
  141. ```json
  142. {
  143. // rest of config...
  144. "args": [
  145. "mcp-remote",
  146. "https://mcp.jina.ai/v1",
  147. "--header",
  148. "Authorization:${AUTH_HEADER}" // note no spaces around ':'
  149. ],
  150. "env": {
  151. "AUTH_HEADER": "Bearer <JINA_API_KEY>" // spaces OK in env vars
  152. }
  153. },
  154. ```
  155. ### Cursor shows a red dot on this MCP status
  156. [Likely a Cursor UI bug](https://forum.cursor.com/t/why-is-my-mcp-red/100518). The MCP works. Toggling off/on clears the dot; on a remote MCP that restarts the local proxy, not a server.
  157. ![cursor shows red dot](/.readme/image3.jpg)
  158. ### My LLM never uses some tools
  159. If all tools are enabled but the model still ignores some, that is expected: models call the tools they were trained on. [Some research says LLMs must be trained to use a tool family](https://arxiv.org/abs/2508.09303). In Cursor, add this rule to a `.mdc` file:
  160. ```text
  161. ---
  162. alwaysApply: true
  163. ---
  164. 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 follow with read_url on the result URLs. One read_url call can take up to 5 URLs at once.
  165. ```
  166. ### A tool returned an error. What does it mean?
  167. A failed call comes back with `isError: true` and the reason in plain text. A call with several queries or URLs is an error only if all of them failed; otherwise each failure is reported next to the results that did come back.
  168. | The message says | It means | What to do |
  169. |---|---|---|
  170. | `Please set your API key ...` | The tool needs a key and none was sent | Add the `Authorization: Bearer` header |
  171. | `Authentication failed ... Reason given: ...` | A key was sent and the API rejected it. The reason is the API's own, for example an unknown key | Check the key. A rejection can be remembered for up to 5 minutes after you fix it |
  172. | `403 Forbidden - Jina billing rejected this API key: ...` | The key is known but could not be charged | Check its balance |
  173. | `This key is out of quota ...` | The balance is used up | Top up |
  174. | `Rate limit exceeded ...` | Your key's rate limit on the Embeddings, Reranker or Reader API | Wait, or upgrade the key. `Retry after Ns.` is given when the API named a wait |
  175. | `The search service is temporarily at capacity ...` | The search backend had no free capacity. It is not about your key | Retry in a few seconds |
  176. | `503 ... PDF extraction is at capacity ... Retry after 10s.` | Both PDF renderers were busy | Retry after the wait |
  177. | `504 ... Failed to download PDF: ... (not finished after ...)` | The source was too slow | Retry later |
  178. | `502 ... Failed to download PDF: ... (the source answered 403)` | The source refused the download. The document may well exist | Retry later, or read it with `read_url` |
  179. | `... timed out after 30000ms` | No answer within the tool's time limit | Retry |
  180. Time limits per tool are listed live at [mcp.jina.ai](https://mcp.jina.ai/) under `time_limits`, printed from the values the server uses.
  181. ### Why is my content truncated?
  182. Claude Code, Claude Desktop, and Cursor enforce a fixed 25k token limit on MCP tool responses. To stop these clients from rejecting a large response outright, this server applies a token guardrail to `read_url`.
  183. Items are kept whole, in order, while they fit. The first that does not fit is cut to a prefix that does, and later items are dropped. A `[jina-mcp] ...` note records what was truncated or omitted, so a partial document is marked partial. At least one item always survives, even one over budget.
  184. The server targets below the limit. It counts tokens with cl100k, the client with its own tokenizer, the cut is a proportional character estimate, and the client measures the serialized JSON payload instead of the raw text. It therefore also enforces a ceiling of 3 bytes per allowed token, which holds across tokenizers for ASCII prose (~3.6 bytes/token) and CJK (~3 bytes/token). Cutting short loses part of the content. A rejected response loses all of it.
  185. Any client can set its own budget with `max_tokens` on the endpoint URL (for example `https://mcp.jina.ai/v1?max_tokens=50000`), and `max_tokens=0` disables truncation entirely. Clients with configurable limits, such as OpenAI Codex (`tool_output_token_limit`), are otherwise left alone.
  186. ### Several queries or URLs in one call
  187. `search_web`, `search_arxiv`, `search_ssrn` and `read_url` take a string or an array on `query` / `url`. An array runs every item concurrently in a single round trip. `search_images` takes one query at a time.
  188. ```jsonc
  189. { "url": ["https://react.dev/reference/react/useState",
  190. "https://docs.python.org/3/library/functions.html"],
  191. "question": "what does the hook or built-in return" }
  192. ```
  193. Arrays cap at 5 entries, enforced by the schema. `withAllLinks`, `withAllImages`, `question`, `chunk_size`, `topk`, `ocr` and `page` are set once for the whole array, not per entry: every URL in the call gets the same `question`, and a multi-page OCR needs one call per page.
  194. ### Why is the endpoint called /sse but using Streamable HTTP?
  195. The `/sse` endpoint URL is kept for backward compatibility with existing users. The recommended endpoint is now `/v1`. Both use the same **Streamable HTTP** transport (the new MCP standard from spec 2025-03-26), not the deprecated SSE transport.
  196. This works because:
  197. - **Claude Desktop, Cursor, Windsurf** use `mcp-remote` which defaults to `http-first` strategy (tries Streamable HTTP first)
  198. - **Claude Code** has native support for both transports
  199. - **LM Studio** supports direct connection to Streamable HTTP endpoints
  200. The response streaming still uses SSE format (`Content-Type: text/event-stream`), but the protocol layer (session management, initialization) follows Streamable HTTP spec. All major MCP clients are compatible.
  201. ### Client-side tool filtering with mcp-remote
  202. If you're using [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) as a local proxy, you can also filter tools client-side using its `--ignore-tool` flag:
  203. ```json
  204. {
  205. "mcpServers": {
  206. "jina-mcp-server": {
  207. "command": "npx",
  208. "args": [
  209. "mcp-remote",
  210. "https://mcp.jina.ai/v1",
  211. "--header",
  212. "Authorization: Bearer ${JINA_API_KEY}",
  213. "--ignore-tool", "search_images",
  214. "--ignore-tool", "search_ssrn",
  215. "--ignore-tool", "extract_pdf"
  216. ]
  217. }
  218. }
  219. }
  220. ```
  221. This filters at the proxy level before tools reach the client. Server-side filtering via query parameters (see [Tool Filtering](#tool-filtering-before-registering)) is cheaper, because the tokens are never sent.
  222. ### Reading a page with a question in mind
  223. `read_url` returns the whole page. Pass `question` and the page is chunked, its passages are scored against the query by [Reranker](https://jina.ai/reranker) v3.5, and only the highest-scoring ones are returned.
  224. | Parameter | Default | Effect |
  225. |---|---|---|
  226. | `question` | *(unset)* | Unset returns the full page. Set returns passages instead of `content`. |
  227. | `chunk_size` | `100` | Target passage size in words, split at sentence boundaries, so a target, not a hard cut. Counted in words in every script. 1-4096. |
  228. | `topk` | `1` | Passages to keep, best first. 1-50. |
  229. `question` gates the other two. Without it the response is unchanged from a plain read.
  230. ```jsonc
  231. // full page: 69,530 bytes
  232. { "url": "https://www.paulgraham.com/greatwork.html" }
  233. // passages: 1,195 bytes
  234. { "url": "https://www.paulgraham.com/greatwork.html",
  235. "question": "Why are new ideas hard to see?", "topk": 3, "chunk_size": 50 }
  236. ```
  237. Response shape: `question`, `snippets`, `snippet_source: content`, no `content`. `snippets` is one element holding up to `topk` passages joined by ` … `. No score is returned, so relevance cannot be thresholded here. Ladder measured at `chunk_size=40`: `topk` 1 gives 433 bytes and no separator, 2 gives 699 bytes and one separator, 5 gives 1,537 bytes and one separator. Fewer than `topk` passages can come back.
  238. If extraction cannot run — empty page, unreadable page, no API key to rank with, or the ranking call itself failed — the full body comes back with `snippet_source: full_content` and a `note`. `snippet_source: content` therefore always means a ranked passage, never just the top of the page.
  239. Byte cost, same URL, same endpoint, bytes of returned text:
  240. | page | plain read | with `question` |
  241. |---|---|---|
  242. | docs.python.org/3/library/functions.html | 83,786 | 874 |
  243. | en.wikipedia.org/wiki/List_of_countries_by_GDP_(nominal) | 12,295 | 912 |
  244. | paulgraham.com/greatwork.html | 69,530 | 1,195 |
  245. Measured against a local `wrangler dev` of this repo with an API key. `r.jina.ai` returns different sizes for the same URL, so do not mix the two sets.
  246. Verified on this build: Python docs, Chinese Wikipedia, React references, GitHub READMEs, arXiv PDFs, essays. Compound questions worked here too (the os.path query returned both the `join` rule and the `splitext` example, and Beijing returned both population and area), so ask one thing per call as a habit, not because every multi-part question fails.
  247. Reproduced failure modes. The response does not flag any of these:
  248. - **Positional questions fail.** Ranking matches text, not document order. `raw.githubusercontent.com/vitejs/vite/main/packages/vite/CHANGELOG.md` is 283,749 bytes and opens with `## [8.3.0] ... (2026-09-10)`. Asked for the latest released version, it returned 1,008 bytes containing `6.0.0` and no `8.3.0` at all. Read the first screen for latest, first, current.
  249. - **Tables, fenced code and page furniture are removed before ranking.** [read.ts](src/utils/read.ts) says so and it holds: the GDP list page is 12,295 bytes through `read_url` and contains `Japan` but not `4,379,253`. Asked for Japan's figure, `question` returned the map colour legend, `$1–5 trillion $750 billion – $1 trillion …`. A number that lives in a table is not reachable this way.
  250. - **Inline code loses tokens.** `curl -fsSL https://bun.sh/install | bash` came back as `curl -fsSL | bash`. Never run a command copied out of a passage without checking the source.
  251. - **Blocked pages return their login wall as content.** `x.com/jina_ai` returned 315 bytes of `Log inSign up … hasn't posted` with `snippet_source: content` and no error.
  252. - **`chunk_size` is not monotonic.** 50 returned 521 bytes opening on the answer (`And yet empirically having new ideas is hard.`); 400 returned 2,260 bytes opening off-topic (`But the relationship is closer than that.`). Use 40-70 for commands, signatures and numbers, 150-200 for explanation.
  253. A question-grounded read is two steps with their own limits: up to 25s for the passages (the extraction itself is given 20s and 5s to deliver its answer), then, only if that produced nothing, up to 30s for the full page. A plain read gets 30s. In a URL array carrying a `question`, each URL has 60s for both steps together.
  254. When the full page comes back instead of passages, the response has `snippet_source: full_content` and a `note` saying why:
  255. | `note` says | Cause | What to do |
  256. |---|---|---|
  257. | the key reached the rate limit of the reranker | Passages are ranked under your own API key, and every read with a `question` draws on that key's reranker limit. A batch of them at once can use it up for the better part of a minute. | Send fewer reads with a `question` at once. |
  258. | not ranked within the time limit | Fetching the page and ranking it did not fit in the 20s the extraction is given. | Read it again, or read it without `question`. |
  259. | extraction was unavailable for this page | Anything else: the page has too little text to rank, or the ranking service failed. | Use the full page that was returned. |
  260. | extraction requires a Jina API key | No key was sent. | Add a key. |
  261. About 1 in 100 reads with a `question` loses its ranking (250 of 20,814 on 2026-11-15), nine in ten of those to the rate limit.
  262. ### Reading a scanned document or a PDF
  263. A plain read parses HTML. It returns nothing useful when the text is not in the markup (scanned pages, image-only PDFs), and flattens formulas and table structure otherwise. Pass `ocr` and the rendered page goes through [jina-ocr-v1](https://jina.ai/models/jina-ocr-v1) as an image, returning Markdown with formulas and tables intact.
  264. ```jsonc
  265. { "url": "https://arxiv.org/pdf/2609.03181", "ocr": true } // page 1
  266. { "url": "https://arxiv.org/pdf/2609.03181", "ocr": true, "page": 2 } // page 2
  267. ```
  268. **One page per call.** Page 1 unless `page` says otherwise, so a long document needs one call per page. Measured on arXiv 2609.03181, a 20-page paper:
  269. | | bytes returned | tokens billed |
  270. |---|---|---|
  271. | plain read | 49,466 (whole PDF) | 13,864 |
  272. | `ocr: true` | 2,963 (page 1) | 61,520 |
  273. | `ocr: true, page: 2` | 2,749 (page 2) | 62,720 |
  274. Off by default, because OCR bills more tokens per page than a plain read costs per document. Turn it on when the HTML path fails or the layout matters. `page` is shared across a URL array, so several pages of one document take one call each.
  275. ### Functions have been removed in v1.10.0
  276. The following tools has been proved not effective or simply broken.
  277. | Tool | Use instead |
  278. |---|---|
  279. | `search_web_deep` | `search_web`, then `read_url` with `question` on the pages you pick |
  280. | `parallel_search_web`, `parallel_search_arxiv`, `parallel_search_ssrn`, `parallel_read_url` | pass an array to `query` / `url` on the singletons |
  281. | `expand_query` | rewrite the query yourself; the endpoint returned one near-copy of the input |
  282. | `classify_text` | classify with the model; label scores differed by ~0.006, which is noise |
  283. | `deduplicate_images` | the response carried base64 JPEG data, not just the selected items |
  284. | `search_bibtex` | read the citation from the publisher or DBLP page directly; both backends were failing live |
  285. | `show_api_key` | nothing. It returned the bearer token into the conversation |
  286. ## Developer Guide
  287. ### Local Development
  288. ```bash
  289. # Clone the repository
  290. git clone https://github.com/jina-ai/MCP.git
  291. cd MCP
  292. # Install dependencies
  293. npm install
  294. # Start development server
  295. npm run start
  296. # Type-check, and run the tests
  297. npm run type-check
  298. npm test
  299. ```
  300. `npm test` bundles `test/*.test.ts` with the esbuild that Wrangler already installs and runs them on Node's built-in test runner. Nothing touches the network: `fetch` is stubbed. The tests cover the parts that depend on other services behaving a certain way, which is where this server has broken before: when a `question` read uses the passage it was given and when it reads the full page instead, what each upstream failure is reported as, the blog catalog cache, and that the time limits fit inside each other.
  301. All time limits are in [`src/utils/limits.ts`](src/utils/limits.ts). The version is read from `package.json`; the `/` page and the MCP handshake both report it.
  302. ### Deploy to Cloudflare Workers
  303. [![Deploy to Workers](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/jina-ai/MCP)
  304. This will deploy your MCP server to a URL like: `jina-mcp-server.<your-account>.workers.dev/v1`

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.