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 crawlerweb_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
.envfile: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.batorrun.ps1 - Linux/Mac:
./run.sh(make executable withchmod +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 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