Jinawebsearchmcp

🚀 Jina Web Search MCP

A Model Context Protocol (MCP) server that offers tools for fetching URL content and conducting web searches via the Jina AI API. It's built with the official MCP Python SDK.

🚀 Quick Start

To get started with the Jina Web Search MCP server, you'll need to meet the prerequisites and set up your API key.

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)

API Key Setup

⚠️ Important Note

You need a Jina AI API key to use this server.

1. Obtain your API key from Jina AI.
2. Create a .env file:

   cp .env.example .env
   # Edit .env and add: JINA_API_KEY=your_actual_api_key_here
   

Installation Options

Choose the installation method that suits your needs:

Option 1: Claude Desktop Integration (Easiest)

Install directly into Claude Desktop for immediate use:

# 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:

# 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)

# 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

# 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

✨ Features

• MCP Protocol Compliance: Fully adheres to Model Context Protocol 2025-06-18.
• FastMCP Implementation: Built using the official Python MCP SDK.
• Docker Support: Facilitates easy deployment with Docker and Docker Compose.
• Streamable HTTP Transport: Operates on port 5003 with modern transport.
• Two Core Tools:
  • fetch_url_content: Retrieve content from any URL using the Jina AI crawler.
  • web_search: Conduct web searches with semantic understanding.
• Claude Desktop Integration: Simple 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: Compatible with Windows, Linux, and macOS.
• Comprehensive Logging: Enable debugging and monitoring with detailed logs.

📦 Installation Guide

Refer to the "Installation Options" section above for detailed installation steps.

💻 Usage Examples

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:

{
  "name": "fetch_url_content",
  "arguments": {
    "url": "https://example.com"
  }
}

web_search

Performs a semantic web search using the Jina AI API.

Parameters:

• query (string): Search query to execute

Example Usage:

{
  "name": "web_search",
  "arguments": {
    "query": "latest technology news"
  }
}

📚 Documentation

Configuration

Environment Variables

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)

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:

{
  "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)

🔧 Technical Details

The server is built with the Model Context Protocol Python SDK by Anthropic. It follows the Model Context Protocol 2025-06-18 and uses the Jina AI API for web crawling and search capabilities.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Built with the official Model Context Protocol Python SDK
• Powered by Jina AI for web crawling and search capabilities
• Following the Model Context Protocol specification
• Project created by Qwen3-Coder-30B-A3B-Instruct

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• MCP Documentation: Model Context Protocol Docs
• SDK Documentation: MCP Python SDK