Jina Web Search

GitHub Stars

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.

Framework: Model Context Protocol 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)

API Key Setup

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

1. Get 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

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

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:

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

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

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

---

Built with ❤️ using the Model Context Protocol Python SDK