JinaWebSearchMCP by hypersniper05 - MCP Server

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

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.

Get your API key from Jina AI

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:

Install: mcp install server.py --name "Jina Web Search"
Available tools will appear in Claude's interface
Use naturally: Ask Claude to search the web or fetch URL content
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

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

This project is licensed under the MIT License - see the 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