### Start Development Server

Source: https://github.com/jina-ai/mcp/blob/main/README.md

Start the development server for the MCP project after installing dependencies.

```bash
# Start development server
npm run start
```

--------------------------------

### Show API Key Example

Source: https://github.com/jina-ai/mcp/blob/main/_autodocs/tools-reference.md

Example of how to call the showApiKey tool to verify the API key being used.

```javascript
const token = await mcp.showApiKey();
// Returns the API key being used (for verification)
```

--------------------------------

### Parallel Web Search Example

Source: https://github.com/jina-ai/mcp/blob/main/_autodocs/tools-reference.md

Example demonstrating how to use the parallel_search_web tool with an array of search configurations.

```javascript
const results = await mcp.parallelSearchWeb({
  searches: [
    { query: "transformer models", num: 10 },
    { query: "attention mechanism", num: 10 },
    { query: "neural networks", num: 10 }
  ]
});
```

--------------------------------

### Search Web Examples

Source: https://github.com/jina-ai/mcp/blob/main/_autodocs/tools-reference.md

Examples demonstrating how to use the search_web tool for single, multiple parallel, and location-specific searches.

```javascript
// Single search
const results = await mcp.searchWeb({
  query: "climate change 2024",
  num: 10
});
```

```javascript
// Multiple parallel searches
const results = await mcp.searchWeb({
  query: ["climate change impact", "climate change solutions"],
  num: 15
});
```

```javascript
// Location-specific search
const results = await mcp.searchWeb({
  query: "restaurants",
  location: "Tokyo",
  num: 20
});
```

--------------------------------

### Expand Query Example

Source: https://github.com/jina-ai/mcp/blob/main/_autodocs/tools-reference.md

Example of using the expand_query tool to get variations of a search term.

```javascript
const expanded = await mcp.expandQuery({
  query: "machine learning"
});
// Returns variations like "deep learning", "neural networks", "AI algorithms", etc.
```

--------------------------------

### Primer Tool Usage Example

Source: https://github.com/jina-ai/mcp/blob/main/_autodocs/tools-reference.md

Example of calling the primer tool to obtain contextual information for LLM localization.

```javascript
const context = await mcp.primer();
// Provides LLM with user timezone, location, current time for localized responses
```

--------------------------------

### URL Example with Multiple Filters

Source: https://github.com/jina-ai/mcp/blob/main/_autodocs/configuration.md

Example URL demonstrating the precedence of filters, where 'exclude_tools' takes priority over 'include_tags'.

```text
/v1?include_tags=search&exclude_tools=search_images
# Includes all search tools except search_images
```

--------------------------------

### Deduplicate Images Example

Source: https://github.com/jina-ai/mcp/blob/main/_autodocs/tools-reference.md

Example of how to use the deduplicateImages tool with image URLs and base64 strings.

```javascript
const unique = await mcp.deduplicateImages({
  images: [
    "https://example.com/img1.jpg",
    "https://example.com/img2.jpg",
    "/9j/4AAQSkZJRg..." // base64 image
  ],
  k: 2
});
```

--------------------------------

### Server Info Response Example

Source: https://github.com/jina-ai/mcp/blob/main/_autodocs/configuration.md

An example of the YAML-formatted response from the root '/' endpoint, providing server details, available tools, and filtering explanations.

```yaml
name: "Jina AI Official MCP Server"
version: "1.4.0"
tools:
  - "primer - Provide timezone-aware timestamps..."
  - "read_url - Extract clean content from web pages..."
  # ... more tools
tool_filtering:
  parameters:
    include_tools: "..."
    exclude_tools: "..."
  tags:
    search: ["search_web", "search_arxiv", ...]
    parallel: ["parallel_search_web", "parallel_search_arxiv", ...]
    read: ["read_url", "parallel_read_url", "capture_screenshot_url"]
    utility: ["primer", "show_api_key", "expand_query", "guess_datetime_url", "extract_pdf"]
    rerank: ["sort_by_relevance", "classify_text", "deduplicate_strings", "deduplicate_images"]
```

--------------------------------

### Environment Variable Configuration Example

Source: https://github.com/jina-ai/mcp/blob/main/_autodocs/configuration.md

Example configuration for environment variables, typically set in wrangler.toml or a .env file. These variables control API keys and base URLs.

```toml
# wrangler.toml or .env
JINA_API_KEY = "jina_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"
VITE_GHOST_API_KEY = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
API_BASE_URL = "https://api.custom-proxy.internal"
```

--------------------------------

### Clone MCP Repository and Install Dependencies

Source: https://github.com/jina-ai/mcp/blob/main/README.md

Clone the MCP repository from GitHub and install the necessary Node.js dependencies.

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

# Install dependencies
npm install
```

--------------------------------

### Search Jina Blog Example

Source: https://github.com/jina-ai/mcp/blob/main/_autodocs/tools-reference.md

Example of searching the Jina blog for posts about 'embeddings' and limiting results to 5.

```javascript
const posts = await mcp.searchJinaBlog({
  query: "embeddings",
  num: 5
});
```

--------------------------------

### Search arXiv Example

Source: https://github.com/jina-ai/mcp/blob/main/_autodocs/tools-reference.md

Example of using the search_arxiv tool to find papers related to a specific topic.

```javascript
const papers = await mcp.searchArxiv({
  query: "transformer neural networks",
  num: 10
});
```

--------------------------------

### Curl Request Example for /v1 Endpoint

Source: https://github.com/jina-ai/mcp/blob/main/_autodocs/configuration.md

Example of how to make a POST request to the /v1 endpoint using curl. This demonstrates setting headers, query parameters, and the request body.

```bash
curl -X POST https://mcp.jina.ai/v1?exclude_tags=parallel \
  -H "Authorization: Bearer jina_xxx" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", ...}'
```

--------------------------------

### MCP Client Configuration Example

Source: https://github.com/jina-ai/mcp/blob/main/_autodocs/README.md

Configure the MCP client to connect to the Jina MCP server. This JSON object specifies the server URL and authorization headers.

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

--------------------------------

### primer

Source: https://github.com/jina-ai/mcp/blob/main/_autodocs/tools-reference.md

Get up-to-date contextual information of the current session to provide localized, time-aware responses.

```APIDOC
## primer

### Description
Get up-to-date contextual information of the current session to provide localized, time-aware responses.

### Method
POST

### Endpoint
/tools/primer

### Parameters
None

### Response
#### Success Response (200)
- **content** (Array<{ type: 'text'; text: string (YAML) }>) - Contains session context including timestamp, client info, location, and network details.

### Response Example
```yaml
content:
  - type: text
    text: |
      timestamp:
        utc: "2025-01-15T12:34:56.789Z"
        userTimezone: "America/New_York"
        userLocalTime: "1/15/2025, 7:34:56 AM"
      client:
        ip: "203.0.113.42"
        userAgent: "Mozilla/5.0..."
        acceptLanguage: "en-US,en;q=0.9"
      location:
        country: "US"
        city: "San Francisco"
        region: "California"
        coordinates:
          lat: 37.7749
          lon: -122.4194
        timezone: "America/Los_Angeles"
        isEU: false
      network:
        asn: 15169
        organization: "Google"
        datacenter: "sjc"
        protocol: "h2"
        tlsVersion: "TLSv1.3"
```
```

--------------------------------

### Guess Datetime from URL Example

Source: https://github.com/jina-ai/mcp/blob/main/_autodocs/tools-reference.md

Example of using the guessDatetimeUrl tool to find the best guess for a web page's datetime.

```javascript
const datetime = await mcp.guessDatetimeUrl({
  url: "https://example.com/article"
});
// Returns best_guess: "2025-01-15T10:30:00Z", confidence: 0.95
```

--------------------------------

### Execute Parallel Web Page Reads

Source: https://github.com/jina-ai/mcp/blob/main/_autodocs/tools-reference.md

Example of executing parallel web page reads with specific configurations for links and images, and setting a custom timeout.

```javascript
const results = await mcp.parallelReadUrl({
  urls: [
    { url: "https://example.com/1", withAllLinks: true },
    { url: "https://example.com/2", withAllImages: true },
  ],
  timeout: 30000
});
```

--------------------------------

### Environment Setup for MCP

Source: https://github.com/jina-ai/mcp/blob/main/_autodocs/README.md

Set environment variables required for Jina MCP operations, including API keys and base URLs. Ensure these are exported before running MCP services.

```bash
export JINA_API_KEY="jina_xxxx"
export VITE_GHOST_API_KEY="xxxx"  # for search_jina_blog
export API_BASE_URL="https://api.jina.ai"  # or custom proxy
```

--------------------------------

### LLM Tool Usage Configuration in Cursor

Source: https://github.com/jina-ai/mcp/blob/main/README.md

Configure your .mdc file in Cursor to ensure Jina MCP tools are used, especially when dealing with uncertainty or user doubt. This example specifies when to use search_arxiv, read_url, search_ssrn, and parallel tools.

```text
---
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.
```

--------------------------------

### Get Contextual Information with Primer

Source: https://github.com/jina-ai/mcp/blob/main/_autodocs/tools-reference.md

Retrieve up-to-date contextual information about the current session, such as time, location, and network details, for localized responses. Does not require an API key.

```typescript
server.tool(
  "primer",
  "Get up-to-date contextual information...",
  {},
  async () => { ... }
)
```

--------------------------------

### Jina Reader API Request Body Example

Source: https://github.com/jina-ai/mcp/blob/main/_autodocs/configuration.md

Example JSON request body for the Jina Reader API, specifying URL and custom headers for content extraction and screenshot capture.

```json
{
  "url": "https://example.com",
  "headers": {
    "X-Md-Link-Style": "discarded",
    "X-With-Links-Summary": "all",
    "X-With-Images-Summary": "true",
    "X-Retain-Images": "none"
  }
}
```

--------------------------------

### HTTP Endpoint /

Source: https://github.com/jina-ai/mcp/blob/main/_autodocs/configuration.md

A GET endpoint that provides server information in YAML format, including server details, available endpoints, tool descriptions, and filtering explanations.

```APIDOC
### `/` (Server Info)

**Method**: GET

**Response**: YAML-formatted server information including:
- Server name and version
- Available endpoints
- Tool list with descriptions
- Tool filtering explanation and examples
- Usage configuration

**Example Response**:
```yaml
name: "Jina AI Official MCP Server"
version: "1.4.0"
tools:
  - "primer - Provide timezone-aware timestamps..."
  - "read_url - Extract clean content from web pages..."
  # ... more tools
tool_filtering:
  parameters:
    include_tools: "..."
    exclude_tools: "..."
  tags:
    search: ["search_web", "search_arxiv", ...]
```
```

--------------------------------

### Get Image URLs from Web Search

Source: https://github.com/jina-ai/mcp/blob/main/_autodocs/tools-reference.md

Searches for images and returns their URLs and metadata. Specify the search query, number of results, and set `return_url` to true.

```javascript
// Get image URLs
const urls = await mcp.searchImages({
  query: "sunset over mountains",
  return_url: true,
  num: 5
});
```

--------------------------------

### Search DBLP for BibTeX Entries

Source: https://github.com/jina-ai/mcp/blob/main/_autodocs/utilities.md

Searches the DBLP (Digital Bibliography & Library Project) for computer science papers using provided arguments. Filters results by year and author after retrieval. Detects common BibTeX entry types. The API endpoint is GET https://dblp.org/search/publ/api?q=...&format=json with a 5-second timeout.

```typescript
export async function searchDblp(args: BibtexSearchArgs): Promise<BibtexEntry[]>
```

--------------------------------

### Configure MCP Server to Include Only Search and Read Tools

Source: https://github.com/jina-ai/mcp/blob/main/README.md

This JSON configuration shows how to include only tools tagged with 'search' or 'read' by using `include_tags=search,read` in the URL. This optimizes context window usage.

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

--------------------------------

### Server Initialization

Source: https://github.com/jina-ai/mcp/blob/main/_autodocs/configuration.md

The server is initialized with a default export in `src/index.ts` that includes a `fetch` handler to process incoming HTTP requests and return MCP responses.

```APIDOC
## Server Initialization

**File**: `src/index.ts`

**Default Export**:
```typescript
export default {
  async fetch(request: Request, env: Env, ctx: ExecutionContext) { ... }
}
```

**Entry Point**: `fetch` handler receives HTTP requests and returns MCP responses.
```

--------------------------------

### List All Available Tools

Source: https://github.com/jina-ai/mcp/blob/main/_autodocs/types.md

Provides a comprehensive list of all tools currently available in the MCE project. This can be used for reference or to dynamically load available functionalities.

```typescript
const ALL_TOOLS = [
  "primer",
  "show_api_key",
  "read_url",
  "capture_screenshot_url",
  "guess_datetime_url",
  "search_web",
  "search_arxiv",
  "search_ssrn",
  "search_images",
  "search_jina_blog",
  "search_bibtex",
  "expand_query",
  "parallel_search_web",
  "parallel_search_arxiv",
  "parallel_search_ssrn",
  "parallel_read_url",
  "sort_by_relevance",
  "classify_text",
  "deduplicate_strings",
  "deduplicate_images",
  "extract_pdf"
];
```

--------------------------------

### deduplicate_images

Source: https://github.com/jina-ai/mcp/blob/main/_autodocs/tools-reference.md

Get top-k semantically unique images using Jina CLIP v2 embeddings and submodular optimization.

```APIDOC
## deduplicate_images

### Description
Get top-k semantically unique images using Jina CLIP v2 embeddings and submodular optimization.

### Method
POST

### Endpoint
/tools/deduplicate_images

### Parameters
#### Request Body
- **images** (string[]) - Yes - Image URLs or base64-encoded image strings (no data URI prefix)
- **k** (number) - No - Auto - Number of unique images to return

### Response
#### Success Response (200)
- **content** (Array<{ type: 'image' or 'text'; ... }>) - Mixed array of URLs, Base64 images, or errors.

### Request Example
```json
{
  "images": [
    "https://example.com/img1.jpg",
    "https://example.com/img2.jpg",
    "/9j/4AAQSkZJRg..."
  ],
  "k": 2
}
```

### Response Example
```json
{
  "content": [
    {
      "type": "image",
      "data": "/9j/4AAQSkZJRg..."
    },
    {
      "type": "text",
      "text": "Error processing image: invalid format"
    }
  ]
}
```
```

--------------------------------

### deduplicate_strings

Source: https://github.com/jina-ai/mcp/blob/main/_autodocs/tools-reference.md

Get top-k semantically unique strings from a list using embeddings and submodular optimization. This tool requires a Jina API key.

```APIDOC
## deduplicate_strings

### Description
Get top-k semantically unique strings from a list using embeddings and submodular optimization. This tool requires a Jina API key.

### Method
POST

### Endpoint
/tools/deduplicate_strings

### Parameters
#### Query Parameters
- **strings** (string[]) - Required - Strings to deduplicate
- **k** (number) - Optional - Number of unique strings to return. If not provided, auto-detects optimal k via saturation detection.

### Request Example
```json
{
  "strings": [
    "The cat sat on the mat",
    "A feline rested on the mat",
    "Dogs are loyal animals",
    "Canines are loyal creatures"
  ],
  "k": 2
}
```

### Response
#### Success Response (200)
- **content** (Array) - Array of unique strings. Each item contains `index` and `text`.

#### Response Example
```json
{
  "content": [
    {
      "index": 0,
      "text": "The cat sat on the mat"
    },
    {
      "index": 2,
      "text": "Dogs are loyal animals"
    }
  ]
}
```
```

--------------------------------

### Default Server Initialization

Source: https://github.com/jina-ai/mcp/blob/main/_autodocs/configuration.md

The default export for the server initialization. The fetch handler processes incoming HTTP requests and generates MCP responses.

```typescript
export default {
  async fetch(request: Request, env: Env, ctx: ExecutionContext) { ... }
}
```

--------------------------------

### Deduplicate Strings

Source: https://github.com/jina-ai/mcp/blob/main/_autodocs/tools-reference.md

Get a specified number (k) of semantically unique strings from a list using embeddings and submodular optimization. If k is not provided, the optimal number is auto-detected.

```typescript
server.tool(
  "deduplicate_strings",
  "Get top-k semantically unique strings...",
  {
    strings: z.array(z.string()),
    k: z.number().optional()
  },
  async ({ strings, k }) => { ... }
)
```

```javascript
const unique = await mcp.deduplicateStrings({
  strings: [
    "The cat sat on the mat",
    "A feline rested on the mat",
    "Dogs are loyal animals",
    "Canines are loyal creatures"
  ],
  k: 2
});
// Returns 2 most diverse strings
```

--------------------------------

### Deduplicate Images with Jina CLIP v2

Source: https://github.com/jina-ai/mcp/blob/main/_autodocs/tools-reference.md

Use this tool to get top-k semantically unique images from a list of URLs or base64-encoded strings. Requires a Jina API key.

```typescript
server.tool(
  "deduplicate_images",
  "Get top-k semantically unique images...",
  {
    images: z.array(z.string()),
    k: z.number().optional()
  },
  async ({ images, k }) => { ... }
)
```

--------------------------------

### Execute Jina Blog Search

Source: https://github.com/jina-ai/mcp/blob/main/_autodocs/utilities.md

Executes a search of Jina AI blog posts via the Ghost Content API. Requires search arguments and a Ghost API key.

```typescript
export async function executeJinaBlogSearch(
  searchArgs: SearchJinaBlogArgs,
  ghostApiKey: string
): Promise<SearchResultOrError>
```

--------------------------------

### Configure MCP Server for Clients Lacking Remote MCP Support

Source: https://github.com/jina-ai/mcp/blob/main/README.md

For clients that do not yet support remote MCP servers, use this configuration with `mcp-remote` to establish a local proxy connection to the remote server.

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

--------------------------------

### Configure Jina MCP Server for OpenAI Codex

Source: https://github.com/jina-ai/mcp/blob/main/README.md

Add this TOML configuration to `~/.codex/config.toml` for OpenAI Codex to connect to the Jina MCP server via `mcp-remote`.

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

--------------------------------

### Search Semantic Scholar API

Source: https://github.com/jina-ai/mcp/blob/main/_autodocs/utilities.md

Searches the Semantic Scholar API for academic papers. It requests specific fields and detects entry types from the venue. The API endpoint is GET `https://api.semanticscholar.org/graph/v1/paper/search`.

```typescript
export async function searchSemanticScholar(args: BibtexSearchArgs): Promise<BibtexEntry[]>
```

--------------------------------

### Filter MCP Tools by Tag

Source: https://github.com/jina-ai/mcp/blob/main/_autodocs/README.md

Demonstrates how to filter MCP tools using query parameters on the endpoint URL. This allows clients to include or exclude specific tools or tags.

```bash
/v1?exclude_tags=parallel          # Exclude parallel tools
/v1?include_tags=search,read       # Only search and read
/v1?exclude_tools=search_images    # Exclude specific tool
```

--------------------------------

### Server Information Object

Source: https://github.com/jina-ai/mcp/blob/main/_autodocs/configuration.md

Represents the server's metadata, including its name and version, typically used during server initialization.

```typescript
{
  name: "Jina AI Official MCP Server",
  version: "1.4.0"  // Matches package.json version
}
```

--------------------------------

### Tool Filtering Configuration

Source: https://github.com/jina-ai/mcp/blob/main/_autodocs/configuration.md

Details on how to configure tool filtering using query parameters on the `/v1` endpoint, including parameter precedence and available tags for filtering tools.

```APIDOC
## Tool Filtering Configuration

Tools can be filtered via query parameters on the endpoint URL to reduce token usage in client context windows.

### Query Parameters

| Parameter | Type | Priority | Description |
|-----------|------|----------|-------------|
| exclude_tools | string | 1 (highest) | Comma-separated tool names to exclude |
| exclude_tags | string | 2 | Comma-separated tags to exclude |
| include_tools | string | 3 | Comma-separated tool names to include |
| include_tags | string | 4 (lowest) | Comma-separated tags to include |

**Precedence**: exclude_tools > exclude_tags > include_tools > include_tags

### Available Tags

| Tag | Tools | Use Case |
|-----|-------|----------| 
| `search` | search_web, search_arxiv, search_ssrn, search_images, search_jina_blog, search_bibtex | All search tools |
| `parallel` | parallel_search_web, parallel_search_arxiv, parallel_search_ssrn, parallel_read_url | Parallel versions only |
| `read` | read_url, parallel_read_url, capture_screenshot_url | All reading tools |
| `utility` | primer, show_api_key, expand_query, guess_datetime_url, extract_pdf | Utility tools |
| `rerank` | sort_by_relevance, classify_text, deduplicate_strings, deduplicate_images | Semantic analysis |

### Configuration Examples

**Exclude parallel tools** (saves ~4 tools of context tokens):
```json
{
  "mcpServers": {
    "jina-mcp-server": {
      "url": "https://mcp.jina.ai/v1?exclude_tags=parallel",
      "headers": {
        "Authorization": "Bearer ${JINA_API_KEY}"
      }
    }
  }
}
```

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

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

**Multiple filters** (exclude_tools has priority):
```
/v1?include_tags=search&exclude_tools=search_images
# Includes all search tools except search_images
```
```

--------------------------------

### SearchJinaBlogArgs Interface

Source: https://github.com/jina-ai/mcp/blob/main/_autodocs/types.md

Defines the arguments for searching the Jina AI blog. Use this to find content specifically on the Jina blog.

```typescript
interface SearchJinaBlogArgs {
  query: string;
  num?: number;
  tbs?: string;
}
```

--------------------------------

### executeJinaBlogSearch

Source: https://github.com/jina-ai/mcp/blob/main/_autodocs/utilities.md

Executes a search of Jina AI blog posts using the Ghost Content API. It requires search arguments and a Ghost API key, returning results with title, URL, snippet, date, and reading time.

```APIDOC
## GET https://cms.jina.ai/ghost/api/content/posts/

### Description
Execute a search of Jina AI blog posts via Ghost Content API.

### Method
GET

### Endpoint
https://cms.jina.ai/ghost/api/content/posts/

### Parameters
#### Query Parameters
- **searchArgs** (SearchJinaBlogArgs) - Required - Query, num, tbs
- **ghostApiKey** (string) - Required - Ghost CMS API key (from env)

### Response
#### Success Response (200)
- **title** (string) - The title of the blog post.
- **url** (string) - The URL of the blog post.
- **snippet** (string) - A short snippet of the blog post content.
- **date** (string) - The publication date of the blog post.
- **reading_time** (number) - The estimated reading time in minutes.

#### Error Response
- **error** (string) - An error message if the search fails.
```

--------------------------------

### Add Jina MCP Server for Claude Code

Source: https://github.com/jina-ai/mcp/blob/main/README.md

Use this bash command to add the Jina MCP server for Claude Code. Ensure to remove any previous `--transport sse` configurations before adding.

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

--------------------------------

### Configure MCP Server to Exclude Specific Tools

Source: https://github.com/jina-ai/mcp/blob/main/README.md

This JSON configuration demonstrates how to exclude specific tools, such as 'search_images' and 'deduplicate_images', by using `exclude_tools=` in the URL.

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

--------------------------------

### Search Jina Blog

Source: https://github.com/jina-ai/mcp/blob/main/_autodocs/tools-reference.md

Search Jina AI news and blog posts for articles related to AI, machine learning, and Jina products. Does not require an API key.

```typescript
server.tool(
  "search_jina_blog",
  "Search Jina AI news and blog posts...",
  {
    query: z.union([z.string(), z.array(z.string())]),
    num: z.number().default(30),
    tbs: z.string().optional()
  },
  async ({ query, num, tbs }) => { ... }
)
```

--------------------------------

### Build-Time Constants

Source: https://github.com/jina-ai/mcp/blob/main/_autodocs/configuration.md

Defines constants for server version and name that can be potentially replaced during the build process.

```typescript
const SERVER_VERSION = "1.4.0";  // Can be replaced by build tools
const SERVER_NAME = "jina-mcp";
```

--------------------------------

### Capture Screenshot as Image or URL

Source: https://github.com/jina-ai/mcp/blob/main/_autodocs/tools-reference.md

Shows how to capture a web page screenshot, either as a base64-encoded JPEG image or as a direct URL. Options include capturing only the initial viewport.

```javascript
// Get screenshot as image
const screenshot = await mcp.captureScreenshot({
  url: "https://example.com",
  firstScreenOnly: true
});

// Get screenshot URL instead
const url = await mcp.captureScreenshot({
  url: "https://example.com",
  return_url: true
});
```

--------------------------------

### Capture Web Page Screenshot Configuration

Source: https://github.com/jina-ai/mcp/blob/main/_autodocs/tools-reference.md

Configures the tool for capturing web page screenshots, with options to capture only the first screen or return a URL instead of the image data.

```typescript
server.tool(
  "capture_screenshot_url",
  "Capture high-quality screenshots of web pages...",
  {
    url: z.string().url(),
    firstScreenOnly: z.boolean().default(false),
    return_url: z.boolean().default(false)
  },
  async ({ url, firstScreenOnly, return_url }) => { ... }
)
```

--------------------------------

### search_jina_blog

Source: https://github.com/jina-ai/mcp/blob/main/_autodocs/tools-reference.md

Search Jina AI news and blog posts at jina.ai/news for articles about AI, machine learning, neural search, embeddings, and Jina products.

```APIDOC
## search_jina_blog

### Description
Search Jina AI news and blog posts at jina.ai/news for articles about AI, machine learning, neural search, embeddings, and Jina products.

### Method
POST

### Endpoint
/tools/search_jina_blog

### Parameters
#### Request Body
- **query** (string or string[]) - Yes - Search terms or array for parallel search
- **num** (number) - No - 30 - Results (1-100)
- **tbs** (string) - No - Time-based filter (qdr:h/d/w/m/y)

### Response
#### Success Response (200)
- **content** (Array<{ type: 'text'; text: string (YAML) }>) - Results with title, url, snippet, date, reading_time.

### Request Example
```json
{
  "query": "embeddings",
  "num": 5
}
```

### Response Example
```yaml
content:
  - type: text
    text: |
      title: "Understanding Embeddings in AI"
      url: "https://jina.ai/news/understanding-embeddings/"
      snippet: "A deep dive into what embeddings are and how they are used..."
      date: "2024-12-01"
      reading_time: "5 min"
```
```

--------------------------------

### SearchJinaBlogArgs

Source: https://github.com/jina-ai/mcp/blob/main/_autodocs/types.md

Arguments for searching the Jina Blog. Includes search query and optional result count and time-based filters.

```APIDOC
## SearchJinaBlogArgs

### Description
Arguments for searching the Jina Blog. Includes search query and optional result count and time-based filters.

### Fields
- **query** (string) - Required - Search terms
- **num** (number) - Optional - Results count (1-100), default 30
- **tbs** (string) - Optional - Time-based search filter
```

--------------------------------

### Execute Web Search

Source: https://github.com/jina-ai/mcp/blob/main/_autodocs/utilities.md

Executes a single web search using the Jina Search API. Requires search arguments and a bearer token.

```typescript
export async function executeWebSearch(
  searchArgs: SearchWebArgs,
  bearerToken: string
): Promise<SearchResultOrError>
```

--------------------------------

### ReadUrlConfig Interface

Source: https://github.com/jina-ai/mcp/blob/main/_autodocs/types.md

Defines the configuration for reading content from a URL. Specify the URL and optional flags to extract links and images.

```typescript
interface ReadUrlConfig {
  url: string;
  withAllLinks?: boolean;
  withAllImages?: boolean;
}
```

--------------------------------

### Expand Query

Source: https://github.com/jina-ai/mcp/blob/main/_autodocs/tools-reference.md

Utilize this tool to expand and rewrite search queries using an up-to-date query expansion model. It takes a single search query as input.

```typescript
server.tool(
  "expand_query",
  "Expand and rewrite search queries...",
  { query: z.string() },
  async ({ query }) => { ... }
)
```

--------------------------------

### Workaround for Windows Server Disconnection Bug

Source: https://github.com/jina-ai/mcp/blob/main/README.md

Use this configuration to bypass a bug in Cursor and Claude Desktop (Windows) where spaces in arguments are not escaped. Ensure there are no spaces around the colon in the 'Authorization' header.

```json
{
  // 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
  }
}
```

--------------------------------

### Deploy Command

Source: https://github.com/jina-ai/mcp/blob/main/_autodocs/configuration.md

The command used to deploy the Cloudflare Worker application, typically utilizing the 'wrangler' tool.

```bash
npm run deploy  # Uses wrangler deploy
```

--------------------------------

### Read Single and Multiple URLs

Source: https://github.com/jina-ai/mcp/blob/main/_autodocs/tools-reference.md

Demonstrates how to read content from a single URL or multiple URLs in parallel using the readUrl tool. Supports extracting links and images.

```javascript
// Single URL
const response = await mcp.readUrl({
  url: "https://example.com/article"
});

// Multiple URLs in parallel
const responses = await mcp.readUrl({
  url: ["https://example.com/article1", "https://example.com/article2"]
});

// Extract all links and images
const rich = await mcp.readUrl({
  url: "https://example.com",
  withAllLinks: true,
  withAllImages: true
});
```

--------------------------------

### Parallel Web Page Reading Configuration

Source: https://github.com/jina-ai/mcp/blob/main/_autodocs/tools-reference.md

Defines the configuration for reading multiple web pages in parallel, including URL details and a global timeout. The maximum number of URLs is limited to 5.

```typescript
server.tool(
  "parallel_read_url",
  "Read multiple web pages in parallel...",
  {
    urls: z.array(z.object({
      url: z.string().url(),
      withAllLinks: z.boolean().default(false),
      withAllImages: z.boolean().default(false)
    })).max(5),
    timeout: z.number().default(30000)
  },
  async ({ urls, timeout }) => { ... }
)
```

--------------------------------

### ReadUrlConfig

Source: https://github.com/jina-ai/mcp/blob/main/_autodocs/types.md

Configuration for reading a URL, including the URL itself and options to extract all links and images.

```APIDOC
## ReadUrlConfig

### Description
Configuration for reading a URL, including the URL itself and options to extract all links and images.

### Fields
- **url** (string) - Required - HTTP/HTTPS URL to read
- **withAllLinks** (boolean) - Optional - Extract all hyperlinks from page
- **withAllImages** (boolean) - Optional - Extract all images from page
```

--------------------------------

### Search the Web

Source: https://github.com/jina-ai/mcp/blob/main/_autodocs/tools-reference.md

Use this tool to search the entire web for current information, news, articles, and websites. It supports single or multiple queries, and allows specifying the number of results, time-based search, location, country, and language.

```typescript
server.tool(
  "search_web",
  "Search the entire web...",
  {
    query: z.union([z.string(), z.array(z.string())]),
    num: z.number().default(30),
    tbs: z.string().optional(),
    location: z.string().optional(),
    gl: z.string().optional(),
    hl: z.string().optional()
  },
  async ({ query, num, tbs, location, gl, hl }) => { ... }
)
```

--------------------------------

### HTTP Endpoint /sse

Source: https://github.com/jina-ai/mcp/blob/main/_autodocs/configuration.md

A backward-compatible endpoint for Streamable HTTP, identical in functionality to the `/v1` endpoint, maintained for older client configurations.

```APIDOC
### `/sse` (Backward Compatibility)

**Protocol**: Streamable HTTP (same as `/v1`)

**Note**: Kept for backward compatibility with older client configurations. Both endpoints are identical.
```

--------------------------------

### SearchWebArgs Interface

Source: https://github.com/jina-ai/mcp/blob/main/_autodocs/types.md

Defines the arguments for a web search query. Use this when performing general web searches.

```typescript
interface SearchWebArgs {
  query: string;
  num?: number;
  tbs?: string;
  location?: string;
  gl?: string;
  hl?: string;
}
```

--------------------------------

### SearchArxivArgs Interface

Source: https://github.com/jina-ai/mcp/blob/main/_autodocs/types.md

Defines the arguments for searching the ArXiv academic paper repository. Use this for scientific literature searches.

```typescript
interface SearchArxivArgs {
  query: string;
  num?: number;
  tbs?: string;
}
```

--------------------------------

### executeWebSearch

Source: https://github.com/jina-ai/mcp/blob/main/_autodocs/utilities.md

Executes a single web search using the Jina Search API. It takes search arguments and a bearer token, returning search results or an error.

```APIDOC
## POST https://svip.jina.ai/

### Description
Execute a single web search via Jina Search API.

### Method
POST

### Endpoint
https://svip.jina.ai/

### Parameters
#### Request Body
- **searchArgs** (SearchWebArgs) - Required - Search configuration (query, num, tbs, location, gl, hl)
- **bearerToken** (string) - Required - Jina API key

### Response
#### Success Response (200)
- **query** (string) - The search query.
- **results** (array) - An array of search results.

#### Error Response
- **error** (string) - An error message if the search fails.
```

--------------------------------

### Configure MCP Server for Clients Supporting Remote MCP

Source: https://github.com/jina-ai/mcp/blob/main/README.md

Use this JSON configuration for clients that support remote MCP servers. It specifies the server URL and optional authorization headers.

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

--------------------------------

### readUrlFromConfig

Source: https://github.com/jina-ai/mcp/blob/main/_autodocs/utilities.md

Reads and extracts content from a URL using the Jina Reader API.

```APIDOC
## readUrlFromConfig

### Description
Core function to read and extract content from a URL via Jina Reader API.

### Method
POST

### Endpoint
https://r.jina.ai/

### Headers
- `X-Md-Link-Style: discarded` (discard markdown link formatting)
- `X-With-Links-Summary: all` (if withAllLinks)
- `X-With-Images-Summary: true` (if withAllImages)
- `X-Retain-Images: none` (default, discard images)
- `Authorization: Bearer {token}` (if provided)

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- **urlConfig** (ReadUrlConfig) - Required - URL, withAllLinks, withAllImages
- **bearerToken** (string) - Optional - Jina API key (optional for rate-limited access)

### Returns
`Promise<ReadUrlResponse | ReadUrlError>` — Success contains `url`, `title`, `content`, optionally `links[]` and `images[]`.
```

--------------------------------

### Handle Jina Blog Search Error

Source: https://github.com/jina-ai/mcp/blob/main/_autodocs/errors.md

Failures in searching the Jina blog via the Ghost Content API (cms.jina.ai) may be due to an invalid API key, network errors, or the API being down. Verify the API key and network connectivity.

```javascript
Jina blog search failed for query "{query}": {statusText}
```

--------------------------------

### Execute Parallel arXiv Searches

Source: https://github.com/jina-ai/mcp/blob/main/_autodocs/tools-reference.md

Initiates parallel searches on arXiv. Specify search queries, the number of results per query, and an optional time-based filter for each search.

```javascript
const results = await mcp.parallelSearchArxiv({
  searches: [
    { query: "attention is all you need", num: 5 },
    { query: "BERT language models", num: 5 },
    { query: "vision transformers", num: 5 }
  ]
});
```

--------------------------------

### Error Response Format

Source: https://github.com/jina-ai/mcp/blob/main/_autodocs/errors.md

All tool errors follow a standardized JSON format. This structure indicates an error occurred and provides a descriptive message.

```json
{
  "content": [
    {
      "type": "text",
      "text": "Error message describing what went wrong"
    }
  ],
  "isError": true
}
```

--------------------------------

### Run Parallel arXiv Searches

Source: https://github.com/jina-ai/mcp/blob/main/_autodocs/tools-reference.md

Execute multiple arXiv searches concurrently to gather diverse academic research. Supports up to 5 parallel searches with configurable results per query and an overall timeout.

```typescript
server.tool(
  "parallel_search_arxiv",
  "Run multiple arXiv searches in parallel...",
  {
    searches: z.array(z.object({
      query: z.string(),
      num: z.number().default(30),
      tbs: z.string().optional()
    })).max(5),
    timeout: z.number().default(30000)
  },
  async ({ searches, timeout }) => { ... }
)
```

--------------------------------

### Search Bibtex Sources

Source: https://github.com/jina-ai/mcp/blob/main/_autodocs/utilities.md

Searches both DBLP and Semantic Scholar in parallel, combines, deduplicates, and sorts the results. It returns the top N results, throwing an error if all sources fail.

```typescript
export async function searchBibtex(args: BibtexSearchArgs): Promise<BibtexEntry[]>
```

--------------------------------

### Read URL Content from Configuration

Source: https://github.com/jina-ai/mcp/blob/main/_autodocs/utilities.md

Reads and extracts content from a given URL using the Jina Reader API. It supports optional bearer tokens for authentication and can fetch associated links and images based on the configuration.

```typescript
export async function readUrlFromConfig(
  urlConfig: ReadUrlConfig,
  bearerToken?: string
): Promise<ReadUrlResponse>
```

--------------------------------

### Execute Image Search

Source: https://github.com/jina-ai/mcp/blob/main/_autodocs/utilities.md

Executes a single image search. Requires search arguments and a bearer token.

```typescript
export async function executeImageSearch(
  searchArgs: SearchImageArgs,
  bearerToken: string
): Promise<SearchResultOrError>
```

--------------------------------

### Download JPEG Images from Web Search

Source: https://github.com/jina-ai/mcp/blob/main/_autodocs/tools-reference.md

Searches for images and returns them as base64 encoded JPEGs. Set `return_url` to false to enable this functionality.

```javascript
// Get downloaded JPEG images
const images = await mcp.searchImages({
  query: "vintage car illustration",
  return_url: false
});
```

--------------------------------

### SearchSsrnArgs Interface

Source: https://github.com/jina-ai/mcp/blob/main/_autodocs/types.md

Defines the arguments for searching the SSRN (Social Science Research Network). Similar to ArXiv, but for social science papers.

```typescript
interface SearchSsrnArgs {
  query: string;
  num?: number;
  tbs?: string;
}
```

--------------------------------

### show_api_key

Source: https://github.com/jina-ai/mcp/blob/main/_autodocs/tools-reference.md

Return the bearer token from the Authorization header for debugging.

```APIDOC
## show_api_key

### Description
Return the bearer token from the Authorization header for debugging.

### Method
POST

### Endpoint
/tools/show_api_key

### Parameters
None

### Response
#### Success Response (200)
- **content** (Array<{ type: 'text'; text: string }>) - The bearer token string (e.g., "jina_xxx...").

### Response Example
```json
{
  "content": [
    {
      "type": "text",
      "text": "jina_abcdef1234567890"
    }
  ]
}
```
```

--------------------------------

### shouldApplyGuardrail

Source: https://github.com/jina-ai/mcp/blob/main/_autodocs/utilities.md

Determines if a token guardrail should be applied based on the client's name.

```APIDOC
## shouldApplyGuardrail

### Description
Check if client needs token guardrail based on name.

### Function Signature
```typescript
export function shouldApplyGuardrail(clientName: string | undefined): boolean
```

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- **clientName** (string or undefined) - MCP client name

### Returns
`true` if client is Claude Code, Claude Desktop, or Cursor (case-insensitive match).
```

--------------------------------

### Display API Key

Source: https://github.com/jina-ai/mcp/blob/main/_autodocs/tools-reference.md

Retrieve the bearer token from the Authorization header for debugging purposes. Returns the API key string.

```typescript
server.tool(
  "show_api_key",
  "Return the bearer token from the Authorization header...",
  {},
  async () => { ... }
)
```

--------------------------------

### Execute arXiv Search

Source: https://github.com/jina-ai/mcp/blob/main/_autodocs/utilities.md

Executes a single search for arXiv papers. Requires search arguments and a bearer token.

```typescript
export async function executeArxivSearch(
  searchArgs: SearchArxivArgs,
  bearerToken: string
): Promise<SearchResultOrError>
```

--------------------------------

### SearchArxivArgs

Source: https://github.com/jina-ai/mcp/blob/main/_autodocs/types.md

Arguments for searching the ArXiv database. Includes search query and optional result count and time-based filters.

```APIDOC
## SearchArxivArgs

### Description
Arguments for searching the ArXiv database. Includes search query and optional result count and time-based filters.

### Fields
- **query** (string) - Required - Author names, paper titles, or research topics
- **num** (number) - Optional - Results count (1-100), default 30
- **tbs** (string) - Optional - Time-based search filter
```

--------------------------------

### Parallel Web Search

Source: https://github.com/jina-ai/mcp/blob/main/_autodocs/tools-reference.md

Execute multiple web searches concurrently to gather comprehensive topic coverage and diverse perspectives. This tool is limited to a maximum of 5 searches and has a configurable timeout.

```typescript
server.tool(
  "parallel_search_web",
  "Run multiple web searches in parallel...",
  {
    searches: z.array(z.object({
      query: z.string(),
      num: z.number().default(30),
      tbs: z.string().optional(),
      location: z.string().optional(),
      gl: z.string().optional(),
      hl: z.string().optional()
    })).max(5),
    timeout: z.number().default(30000)
  },
  async ({ searches, timeout }) => { ... }
)
```

--------------------------------

### Search Web Images

Source: https://github.com/jina-ai/mcp/blob/main/_autodocs/tools-reference.md

Find images across the web, similar to Google Images. Requires a Jina API key. Can return image URLs or download images as base64 encoded JPEGs.

```typescript
server.tool(
  "search_images",
  "Search for images across the web...",
  {
    query: z.string(),
    return_url: z.boolean().default(false),
    tbs: z.string().optional(),
    location: z.string().optional(),
    gl: z.string().optional(),
    hl: z.string().optional()
  },
  async ({ query, return_url, tbs, location, gl, hl }) => { ... }
)
```

--------------------------------

### Request Context Data Structure

Source: https://github.com/jina-ai/mcp/blob/main/_autodocs/configuration.md

Illustrates the structure of the request context object, which includes timestamp, client, location, and network details extracted from Cloudflare Workers.

```typescript
const context = {
  timestamp: {
    utc: "ISO date string",
    userTimezone?: "Region/City",
    userLocalTime?: "Localized date string"
  },
  client?: {
    ip: "IP address",
    userAgent: "User-Agent header",
    acceptLanguage: "Accept-Language header"
  },
  location?: {
    country: "Country code",
    city: "City name",
    region: "Region name",
    regionCode: "Region code",
    continent: "Continent",
    postalCode: "Postal code",
    coordinates?: { lat: number, lon: number },
    timezone: "Region/City",
    isEU: boolean
  },
  network?: {
    asn: "Autonomous System Number",
    organization: "ISP/Organization name",
    datacenter: "Cloudflare colo code",
    protocol: "HTTP protocol version",
    tlsVersion: "TLS version"
  }
}
```