@ildunari/jina-mcp-advanced/README.md

Pure MCP Server for Jina.AI Advanced web scraping

# Jina MCP Advanced

Pure MCP Server for Jina.AI Advanced web scraping capabilities. This server provides access to Jina's powerful web content extraction API through the Model Context Protocol.

## Features

- 🔍 Advanced web scraping with Jina Reader
- 📄 Multiple output formats (markdown, HTML, text, screenshots)
- 🧠 Support for JavaScript-heavy sites with browser engine
- 🎯 CSS selector targeting for specific content
- 🖼️ Image handling and captioning
- ⚡ Fast and reliable content extraction

## Installation

### NPX (Recommended)

```bash
# No installation needed - run directly
npx @ildunari/jina-mcp-advanced
```

### Global Installation

```bash
npm install -g @ildunari/jina-mcp-advanced
jina-mcp
```

## Setup

### 1. Get Jina API Key

Get your free API key from [Jina AI](https://jina.ai/api).

### 2. Claude Desktop Configuration

Add this to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "jina-advanced": {
      "command": "npx",
      "args": ["@ildunari/jina-mcp-advanced"],
      "env": {
        "JINA_API_KEY": "your-jina-api-key-here"
      }
    }
  }
}
```

Or if installed globally:

```json
{
  "mcpServers": {
    "jina-advanced": {
      "command": "jina-mcp",
      "env": {
        "JINA_API_KEY": "your-jina-api-key-here"
      }
    }
  }
}
```

### 3. Restart Claude Desktop

After updating the configuration, restart Claude Desktop to load the new MCP server.

## Available Tools

### `read_webpage`

Fetch and extract content from any URL using Jina Reader Advanced.

**Parameters:**
- `url` (required) - The URL to scrape
- `return_format` - Output format: `markdown`, `html`, `text`, `screenshot`, `pageshot` (default: `markdown`)
- `engine` - Rendering engine: `default` or `browser` (use `browser` for JS-heavy sites)
- `retain_images` - Whether to include images (default: `false`)
- `summarize_links` - Include link summaries (default: `true`)
- `summarize_images` - Include image summaries (default: `false`)
- `image_caption` - Generate image captions (default: `false`)
- `use_readerlm` - Use ReaderLM for enhanced understanding (default: `false`)
- `bypass_cache` - Force fresh content fetch (default: `false`)
- `target_selector` - CSS selector for specific content
- `wait_for_selector` - Wait for element before scraping
- `exclude_selector` - Elements to exclude from scraping
- `timeout` - Request timeout in seconds

## Usage Examples

After setup, you can use these commands in Claude:

```
Read the content from https://example.com and summarize it
```

```
Extract the main article from https://news-site.com using CSS selector ".article-content"
```

```
Take a screenshot of https://dashboard.example.com using browser engine
```

## Environment Variables

- `JINA_API_KEY` - Your Jina AI API key (required)

## Troubleshooting

### MCP Server Not Working

1. **Check configuration**: Ensure your `claude_desktop_config.json` is valid JSON
2. **Verify API key**: Make sure your `JINA_API_KEY` is correct
3. **Restart Claude**: Restart Claude Desktop after configuration changes
4. **Check logs**: Look at Claude Desktop's logs for error messages

### API Key Issues

- Get your API key from [Jina AI Dashboard](https://jina.ai/api)
- Make sure the key has sufficient credits/permissions
- Verify the key is correctly set in the environment variables

## License

MIT

## Support

For issues and feature requests, please visit the [GitHub repository](https://github.com/ildunari/jina-mcp-advanced).