Jina Web Search MCP

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

Related MCP server: Jina AI MCP Server

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

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