Jina AI MCP Tools
This server exposes one tool, jina_reader, for fetching and extracting readable content from web pages.
Read/extract content from a web page given its
url(required, URI format).Paginate long documents with
page(1-indexed, default 1); pages are ~15,000 tokens, cached in an LRU of 50 URLs for instant follow-up reads.Override the fetch timeout via
customTimeoutin whole seconds (max 2,147,483) for slow sites.Behind the scenes it converts GitHub file URLs (branches/tags/commits) to raw content and tries direct markdown retrieval for allowlisted hosts before falling back to
r.jina.ai.Note: no search tool is present in this schema, so only page reading is available here.
Enables searching of GitHub repositories and provides specialized support for reading GitHub file URLs by automatically converting them to raw content URLs for improved extraction.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Jina AI MCP Tools search for the latest news on AI safety regulations"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Jina AI MCP Tools
Web search and page reading for coding agents. Two tools, no tool-catalog buffet.
jina-mcp-tools is an unofficial, deliberately small Model Context Protocol (MCP) server built on Jina AI Reader and Search.
It gives Codex, Claude Code, and other coding agents the two web capabilities they usually need while programming:
Find a small set of relevant pages.
Read the pages that actually matter.
That is the whole menu. No embeddings, screenshotting, image search, classification, reranking, or PDF archaeology. Those are useful tools—just not always useful tools to carry into every coding session.
This is an unofficial community project. It is not affiliated with or endorsed by Jina AI, and it uses Jina AI APIs rather than replacing them.
Why Another Jina Integration?
Jina already provides an excellent official MCP server and official CLI. They are designed to expose a broad range of Jina capabilities. This project makes a different tradeoff: it treats context space and tool-selection attention as resources worth saving.
MCP tool definitions typically enter an agent's context before the real work begins. A broad catalog is valuable when the agent needs it; for everyday programming research, it can be more menu than meal. jina-mcp-tools exposes at most two focused tools and follows one deliberately boring workflow:
Search the web and receive a short list of results.
Pick the useful URLs.
Read those pages, one manageable page at a time.
Get back to the code.
Boring infrastructure is often very considerate infrastructure.
Related MCP server: Jina Web Search MCP
Which Jina Integration Should I Use?
| |||
Interface | Local or self-hosted MCP over stdio/HTTP | Hosted remote MCP | Shell commands |
Default scope | Web search and page reading | Broad Jina tool catalog | Broad Jina command suite |
Context approach | At most two small tool definitions | Server-side tool filters are available | Uses the agent's existing shell tool and progressive |
Large pages | Explicit token-based pagination with an LRU cache | Client-aware response guardrails | Standard output and Unix pipes |
Best fit | Coding agents that want a small native MCP surface | Hosted access, research tools, images, PDFs, embeddings, or reranking | Agents and humans who want pipes, JSON, scripting, and the wider Jina platform |
Choose jina-mcp-tools when native MCP integration, a minimal default tool surface, and paginated reading matter most.
Choose the official MCP server when you want a hosted endpoint or need its wider capabilities. It can also be narrowed with include_tools or include_tags, which is a good option when hosting convenience matters more than running a local process.
Choose the official CLI when your agent already has reliable shell access and you want Unix composition or the full Jina API suite without registering a large MCP catalog.
MCP Protocol Compatibility
The same server supports both the current MCP 2026-07-28 protocol and legacy initialize-era clients over stdio and Streamable HTTP. Modern clients can use server/discover and per-request protocol metadata; older clients continue through the SDK's legacy compatibility path.
MCP's cursor pagination applies to discovery operations such as tools/list and resources/list. The page parameter on jina_reader is separate application-level content chunking: it keeps one large document from becoming an oversized tools/call result, which MCP does not paginate automatically.
Quick Start
Prerequisites
Node.js 20 or later.
A Jina AI API key for web search. The reader works without a key, subject to Jina's unauthenticated rate limits.
Set the API key in your shell if you want both search and reading:
export JINA_API_KEY=jina_your_api_keyCodex
codex mcp add jina-web --env JINA_API_KEY="$JINA_API_KEY" -- npx -y jina-mcp-toolsClaude Code
claude mcp add --scope user \
--env JINA_API_KEY="$JINA_API_KEY" \
--transport stdio jina-web -- npx -y jina-mcp-toolsOmit the API-key option from either command for reader-only mode.
VS Code
VS Code stores MCP configuration in a user-profile mcp.json or a workspace-level .vscode/mcp.json. Its configuration uses servers, not mcpServers. This example securely prompts for the API key and stores it using VS Code's input-variable support:
{
"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}"
}
}
}
}Open the user configuration with MCP: Open User Configuration, or save the file as .vscode/mcp.json to share the server configuration with a workspace. Remove env and inputs for reader-only mode.
For a reader-only user-profile installation from the command line:
code --add-mcp "{\"name\":\"jina-web\",\"type\":\"stdio\",\"command\":\"npx\",\"args\":[\"-y\",\"jina-mcp-tools\"]}"Claude Desktop, Cursor, and Other MCP Clients
For clients that use the mcpServers JSON format:
{
"mcpServers": {
"jina-web": {
"command": "npx",
"args": [
"-y",
"jina-mcp-tools"
],
"env": {
"JINA_API_KEY": "your_jina_api_key_here"
}
}
}
}The default transport is stdio. Remove the env block for reader-only mode.
Available Tools
jina_reader
Extract and read content from a web page.
Parameters:
url— URL to read (required).page— Page number for paginated content (default:1).customTimeout— Timeout override in seconds (optional).
Designed for coding-agent research:
Automatically paginates large documents instead of returning one oversized response.
Keeps an LRU cache so later pages of the same URL are available immediately.
Converts GitHub file URLs for branches, tags, and commits to raw content URLs.
Tries direct
Accept: text/markdownretrieval for a maintained allowlist of documentation and blog hosts, then falls back tor.jina.aiif the response fails or is empty.
The default cache holds 50 URLs, and each page is limited to approximately 15,000 tokens. Both values are configurable.
jina_search / jina_search_vip
Search the web and return a lightweight shortlist. Use jina_reader to retrieve the full content of promising results. A Jina API key is required.
Only one search tool is registered, depending on --search-endpoint:
jina_searchusess.jina.ai(standard, the default).jina_search_vipusessvip.jina.ai(vip).
Parameters:
query— Search query (required).count— Number of results (default:5).siteFilter— Limit results to a domain such asgithub.com.
The small default result count is intentional: search first, read selectively, and leave some context for the repository you were working on in the first place.
Configuration
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 helpHTTP Transport
HTTP mode is intended for self-hosted deployments or clients that cannot spawn a local stdio process.
Start the server:
# 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 3000Connect to http://localhost:3000/mcp:
Codex:
codex mcp add jina-web --url http://localhost:3000/mcpClaude Code:
claude mcp add --transport http jina-web http://localhost:3000/mcpMCP Inspector:
npx -y @modelcontextprotocol/inspectorVS Code:
code --add-mcp "{\"name\":\"jina-web\",\"type\":\"http\",\"url\":\"http://localhost:3000/mcp\"}"
HTTP Security
HTTP mode binds to 127.0.0.1 by default. For a remote deployment, put the server behind TLS and require a bearer token:
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 3000Clients must send:
Authorization: Bearer change-meBrowser-origin requests are limited to localhost by default. Set JINA_MCP_ALLOWED_ORIGINS to a comma-separated allowlist of complete origins for browser-based remote clients, for example https://app.example.com.
Loopback HTTP binds validate the Host header automatically. When binding to 0.0.0.0 or ::, set JINA_MCP_ALLOWED_HOSTS to a comma-separated list of public hostnames accepted by the server, without schemes or ports. This protects the endpoint against DNS-rebinding and unexpected proxy hostnames.
Running the MCP process locally does not make Jina requests offline: search and most reader requests still call Jina AI services. Some allowlisted markdown hosts and GitHub file URLs may be fetched directly.
Proxy Environment Variables
To route outbound requests through a proxy, enable Node's proxy environment support and provide the proxy URLs:
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-toolsFor MCP clients that use the mcpServers configuration format, include the same environment variables:
{
"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"
}
}
}
}Alternatively, start Node with NODE_OPTIONS=--use-env-proxy. Proxy URLs are only used when proxy environment support is enabled.
Development and testing
Run pnpm verify to typecheck production and test code, build, and run all tests.
Run pnpm test:e2e for the compiled MCP transport suite alone. It covers stdio
and HTTP with legacy and modern protocol negotiation, reader/search calls,
pagination, upstream requests, and error recovery without real API credentials.
Run pnpm test:live for opt-in real Jina calls using an exported JINA_API_KEY.
See the test plan for coverage, boundaries, and a real Codex
client workflow. See architecture and
contributing for module boundaries and development/release steps.
Scope and Non-Goals
This project intentionally does not aim to expose every Jina API. It is not the right choice when you need embeddings, reranking, classification, screenshots, image or academic search, query expansion, deduplication, or structured PDF extraction. Use the official MCP server or CLI for those jobs.
The narrow scope is the feature. If this server grows twenty tools and develops a small cockpit, something has gone terribly wrong.
License
MIT
Links
Available Tools
1 tooljina_readerJina Web ReaderC
Read and extract content from web page.
Inputs: url (required), page, customTimeout.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 1 tool
There is only one tool, so there is no possibility of confusion or misselection. Its purpose is clearly distinct.
With a single tool named jina_reader, consistency is trivially satisfied. It follows a readable snake_case pattern.
A server branded as 'Jina AI MCP Tools' with only one tool seems too few for the apparent scope. Jina AI typically offers multiple capabilities (search, embeddings, reranking), so one tool feels under-provisioned.
The surface only covers web page reading, with no search, embedding, reranking, or other operations implied by the Jina AI brand. This is a severely incomplete toolset for the stated purpose.
Maintenance
Related MCP Connectors
Jina AI Reader/Search MCP — turn any URL into clean LLM-ready markdown, plus web search.
Web search and page reading for AI agents, including JSON APIs, RSS feeds and YouTube.
Web search, Google SERP, page extraction to markdown and cited answers for AI agents.
Web search and content extraction for AI: Google results, any page as Markdown or JSON
Related MCP Servers
- AlicenseBqualityFmaintenanceEnables efficient web search integration with Jina.ai's Search API, offering clean, LLM-optimized content retrieval with support for various content types and configurable caching.114 npm3MIT
- AlicenseNot gradedqualityDmaintenanceEnables web content retrieval and semantic search capabilities through the Jina AI API. Provides tools to fetch content from URLs and perform intelligent web searches with natural language queries.3MIT
- AlicenseNot gradedqualityNot gradedmaintenanceProvides web content extraction, search capabilities (web, arXiv, SSRN, images), semantic deduplication, and reranking through Jina AI's Reader, Embeddings, and Reranker APIs.1Apache 2.0
- AlicenseNot gradedqualityDmaintenanceProvides tools for web content extraction, search, embeddings, reranking, and image processing via Jina AI APIs, enabling intelligent data retrieval and analysis.Apache 2.0