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.
Potencialize seu agente
O comando do próprio publicador. Não é um endpoint do PlugMCP.
Host a copy with our keys and logs.
npx -y [email protected]O Claude Code não tem link de instalação para um comando local. Copie o comando abaixo e execute-o em um terminal.
claude mcp add jina-mcp-tools -- npx -y jina-mcp-tools@1.3.4Execute em um terminal.
{ "mcpServers": { "jina-mcp-tools": { "command": "npx", "args": [ "-y", "[email protected]" ] } }}claude_desktop_config.json
URL remota ou um comando na sua máquina? Como as duas instalações diferem
Rodar no PlugMCP
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
AbrirDo publicador
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.
Jina AI Model Context Protocol (MCP) server that integrates with Jina AI APIs for web reading and search
It gives Codex, Claude Code, and other coding agents the two web capabilities they usually need while programming:
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.
[!NOTE] 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.
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:
Boring infrastructure is often very considerate infrastructure.
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.
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.
Set the API key in your shell if you want both search and reading:
export JINA_API_KEY=jina_your_api_key
codex mcp add jina-web --env JINA_API_KEY="$JINA_API_KEY" -- npx -y jina-mcp-tools
claude mcp add --scope user \
--env JINA_API_KEY="$JINA_API_KEY" \
--transport stdio jina-web -- npx -y jina-mcp-tools
Omit the API-key option from either command for reader-only mode.
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\"]}"
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.
jina_readerExtract 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:
Accept: text/markdown retrieval for a maintained allowlist of documentation and blog hosts, then falls back to r.jina.ai if 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_vipSearch 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_search uses s.jina.ai (standard, the default).jina_search_vip uses svip.jina.ai (vip).Parameters:
query — Search query (required).count — Number of results (default: 5).siteFilter — Limit results to a domain such as github.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.
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 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 3000
Connect to http://localhost:3000/mcp:
codex mcp add jina-web --url http://localhost:3000/mcpclaude mcp add --transport http jina-web http://localhost:3000/mcpnpx -y @modelcontextprotocol/inspectorcode --add-mcp "{\"name\":\"jina-web\",\"type\":\"http\",\"url\":\"http://localhost:3000/mcp\"}"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 3000
Clients must send:
Authorization: Bearer change-me
Browser-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.
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-tools
For 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.
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.
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.
MIT
Jina AI Model Context Protocol (MCP) server that integrates with Jina AI APIs for web reading and search
{ "mcpServers": { "jina-mcp-tools": { "command": "npx", "args": [ "-y", "[email protected]" ] } }}Ferramentas
Ainda não há lista de ferramentas. Servidores remotos recebem uma após a primeira verificação de saúde.
Perguntas frequentes
Copie nesta página a configuração stdio para Cursor, Claude Desktop, Claude Code ou VS Code. Ela usa a instalação do publicador, não um proxy do PlugMCP.
Este registro não lista nenhuma variável de ambiente obrigatória.
Jina MCP Tools roda localmente via stdio.
Última verificação: 2026-11-15. Jina AI Model Context Protocol (MCP) server that integrates with Jina AI APIs for web reading and search