Readme.md•7.75 kB
# Jina Web Search MCP
[](https://github.com/hypersniper05/JinaWebSearchMCP/stargazers)
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](https://github.com/modelcontextprotocol/python-sdk).
**Framework**: [Model Context Protocol Python SDK](https://github.com/modelcontextprotocol/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](https://jina.ai/))
## API Key Setup
> **Important**: You need a Jina AI API key to use this server.
1. Get your API key from [Jina AI](https://jina.ai/)
2. Create a `.env` file:
```bash
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:
```bash
# 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:
```bash
# 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)
```bash
# 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
```bash
# 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:**
```json
{
"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:**
```json
{
"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:**
```json
{
"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](LICENSE) file for details.
## Acknowledgments
- Built with the official [Model Context Protocol Python SDK](https://github.com/modelcontextprotocol/python-sdk)
- Powered by [Jina AI](https://jina.ai/) for web crawling and search capabilities
- Following the [Model Context Protocol](https://modelcontextprotocol.io) specification
- Project created by [Qwen3-Coder-30B-A3B-Instruct](https://huggingface.co/Qwen/Qwen3-Coder-30B-A3B-Instruct)
## Support
- **Issues**: [GitHub Issues](https://github.com/hypersniper05/JinaWebSearchMCP/issues)
- **Discussions**: [GitHub Discussions](https://github.com/hypersniper05/JinaWebSearchMCP/discussions)
- **MCP Documentation**: [Model Context Protocol Docs](https://modelcontextprotocol.io/docs)
- **SDK Documentation**: [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)
---
*Built with ❤️ using the [Model Context Protocol Python SDK](https://github.com/modelcontextprotocol/python-sdk)*