# Jina Web Search MCP

![Docker](https://img.shields.io/badge/Docker-Ready-2496ED?style=flat-square&logo=docker&logoColor=white)
![Python](https://img.shields.io/badge/Python-3.8+-3776AB?style=flat-square&logo=python&logoColor=white)
![MCP](https://img.shields.io/badge/MCP-2025--06--18-000000?style=flat-square&logo=data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMjQiIGhlaWdodD0iMjQiIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KPHBhdGggZD0iTTEyIDJMMTMuMDkgOC4yNkwyMCA5TDEzLjA5IDE1Ljc0TDEyIDIyTDEwLjkxIDE1Ljc0TDQgOUwxMC45MSA4LjI2TDEyIDJaIiBmaWxsPSJ3aGl0ZSIvPgo8L3N2Zz4K&logoColor=white)
![License](https://img.shields.io/badge/License-MIT-000000?style=flat-square&logo=opensourceinitiative&logoColor=white)
[![GitHub Stars](https://img.shields.io/github/stars/hypersniper05/JinaWebSearchMCP?style=flat-square&logo=github&logoColor=white&color=000000)](https://github.com/hypersniper05/JinaWebSearchMCP/stargazers)

A Model Context Protocol (MCP) server that provides tools for fetching URL content and performing web searches using the Jina AI API. Built with the [official MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk).

**Framework**: [Model Context Protocol Python SDK](https://github.com/modelcontextprotocol/python-sdk) by Anthropic

## Features

- **MCP Protocol Compliance**: Fully compliant with Model Context Protocol 2025-06-18
- **FastMCP Implementation**: Built with the official Python MCP SDK
- **Docker Support**: Easy deployment with Docker and Docker Compose
- **Streamable HTTP Transport**: Runs on port 5003 with modern transport
- **Two Core Tools**:
  - `fetch_url_content`: Fetch content from any URL using Jina AI crawler
  - `web_search`: Perform web searches with semantic understanding
- **Claude Desktop Integration**: Easy installation with `mcp install`
- **Development Tools**: Built-in testing with `mcp dev`
- **Error Handling**: Graceful error responses for failed requests
- **Environment Configuration**: Configurable API keys via environment variables
- **Cross-Platform**: Works on Windows, Linux, and macOS
- **Comprehensive Logging**: Debug and monitor with detailed logs

## Prerequisites

- **Python 3.8+** (required for MCP)
- **Docker & Docker Compose** (recommended for deployment) OR
- **uv** (recommended) or **pip** for package management
- **Jina AI API Key** ([Get one here](https://jina.ai/))

## API Key Setup

> **Important**: You need a Jina AI API key to use this server.

1. Get your API key from [Jina AI](https://jina.ai/)
2. Create a `.env` file:
   ```bash
   cp .env.example .env
   # Edit .env and add: JINA_API_KEY=your_actual_api_key_here
   ```

## Installation Options

### Option 1: Claude Desktop Integration (Easiest)

Install directly into Claude Desktop for immediate use:

```bash
# Clone the repository
git clone https://github.com/hypersniper05/JinaWebSearchMCP.git
cd JinaWebSearchMCP

# Set your API key
export JINA_API_KEY=your_actual_api_key_here  # Linux/Mac
# OR
set JINA_API_KEY=your_actual_api_key_here     # Windows

# Install dependencies and add to Claude Desktop
pip install -r requirements.txt
mcp install server.py --name "Jina Web Search"
```

### Option 2: Development & Testing

Test and debug your server with the MCP Inspector:

```bash
# Install dependencies (using uv - recommended)
uv add mcp[cli] requests

# Test with MCP development tools
uv run mcp dev server.py

# Or using pip
pip install -r requirements.txt
mcp dev server.py
```

### Option 3: Docker (Production)

```bash
# Clone the repository
git clone https://github.com/hypersniper05/JinaWebSearchMCP.git
cd JinaWebSearchMCP

# Set your API key in .env file
cp .env.example .env
# Edit .env and set your JINA_API_KEY

# Build and run with Docker Compose
docker-compose up -d

# Check logs
docker-compose logs -f

# Stop the server
docker-compose down
```

**Easy startup scripts:**
- **Windows**: `run.bat` or `run.ps1`
- **Linux/Mac**: `./run.sh` (make executable with `chmod +x run.sh`)

### Option 4: Direct Execution

```bash
# Install dependencies
pip install -r requirements.txt

# Set environment variable
export JINA_API_KEY=your_api_key_here  # Linux/Mac
# OR
set JINA_API_KEY=your_api_key_here     # Windows

# Run the server directly
python server.py
```

The server will be available at `http://localhost:5003`

## Configuration

### Environment Variables

| Variable | Description | Required | Default |
|----------|-------------|----------|---------|
| `JINA_API_KEY` | Your Jina AI API key | **Yes** | `your_jina_api_key_here` |

### Server Configuration

- **Host**: `0.0.0.0` (all interfaces for Docker compatibility)
- **Port**: `5003`
- **Transport**: Streamable HTTP (modern MCP transport)
- **Protocol**: Model Context Protocol 2025-06-18
- **Framework**: FastMCP (official Python SDK)


## Available Tools

### `fetch_url_content`
Fetches and returns content from a given URL using Jina AI's crawler service.

**Parameters:**
- `url` (string): The URL to fetch content from

**Example Usage:**
```json
{
  "name": "fetch_url_content",
  "arguments": {
    "url": "https://example.com"
  }
}
```

### `web_search`
Performs a semantic web search using Jina AI API.

**Parameters:**
- `query` (string): Search query to execute

**Example Usage:**
```json
{
  "name": "web_search",
  "arguments": {
    "query": "latest technology news"
  }
}
```

## MCP Integration

### Claude Desktop

Once installed, your server appears in Claude Desktop:

1. **Install**: `mcp install server.py --name "Jina Web Search"`
2. **Available tools** will appear in Claude's interface
3. **Use naturally**: Ask Claude to search the web or fetch URL content
4. **Logs**: Check `~/.config/claude-desktop/` for logs

### Other MCP Clients

This server works with any MCP-compatible client:

- **VS Code MCP Extension**: Connect via streamable HTTP
- **Custom clients**: Use the official MCP Python SDK
- **Browser clients**: Connect to `http://localhost:5003/mcp`


**Client Example:**
```json
{
  "mcpServers": {
    "websearch": {
      "url": "http://localhost:5003/mcp"
    }
  }
}
```

## Docker Details

The Docker setup includes:
- **Multi-stage build optimization** for smaller images
- **Health checks** for container monitoring
- **Environment variable handling** for secure API key management
- **Automatic restart policies** for production reliability
- **Port mapping** for easy access (5003:5003)

## Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes
4. Commit your changes (`git commit -m 'Add some amazing feature'`)
5. Push to the branch (`git push origin feature/amazing-feature`)
6. Open a Pull Request

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Acknowledgments

- Built with the official [Model Context Protocol Python SDK](https://github.com/modelcontextprotocol/python-sdk)
- Powered by [Jina AI](https://jina.ai/) for web crawling and search capabilities
- Following the [Model Context Protocol](https://modelcontextprotocol.io) specification
- Project created by [Qwen3-Coder-30B-A3B-Instruct](https://huggingface.co/Qwen/Qwen3-Coder-30B-A3B-Instruct)

## Support

- **Issues**: [GitHub Issues](https://github.com/hypersniper05/JinaWebSearchMCP/issues)
- **Discussions**: [GitHub Discussions](https://github.com/hypersniper05/JinaWebSearchMCP/discussions)
- **MCP Documentation**: [Model Context Protocol Docs](https://modelcontextprotocol.io/docs)
- **SDK Documentation**: [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)

---

*Built with ❤️ using the [Model Context Protocol Python SDK](https://github.com/modelcontextprotocol/python-sdk)*