🚀 Jina Web Search MCP
Jina Web Search MCP 是一个基于 Model Context Protocol (MCP) 的服务器，借助 Jina AI API 提供获取 URL 内容和执行网络搜索的工具。它使用 官方 MCP Python SDK 构建，为用户提供便捷、高效的网络搜索和内容获取服务。
✨ 主要特性
- MCP 协议兼容：完全符合 2025 - 06 - 18 版本的 Model Context Protocol。
- FastMCP 实现：基于官方 Python MCP SDK 构建。
- Docker 支持：可通过 Docker 和 Docker Compose 轻松部署。
- 可流式 HTTP 传输：运行在 5003 端口，采用现代传输方式。
- 两大核心工具：
fetch_url_content：使用 Jina AI 爬虫从任意 URL 获取内容。web_search：具备语义理解能力，可执行网络搜索。
- Claude Desktop 集成：通过
mcp install即可轻松安装。 - 开发工具：内置
mcp dev用于测试。 - 错误处理：针对失败请求提供优雅的错误响应。
- 环境配置：可通过环境变量配置 API 密钥。
- 跨平台支持：支持 Windows、Linux 和 macOS。
- 全面日志记录：提供详细日志，方便调试和监控。
📦 安装指南
前提条件
- Python 3.8+（MCP 所需）
- Docker 与 Docker Compose（推荐用于部署），或者
- uv（推荐）或 pip 用于包管理
- Jina AI API 密钥（在此获取）
API 密钥设置
⚠️ 重要提示
使用此服务器需要 Jina AI API 密钥。
- 从 Jina AI 获取 API 密钥。
- 创建
.env文件：
cp .env.example .env
# 编辑 .env 文件并添加：JINA_API_KEY=your_actual_api_key_here
安装选项
选项 1：Claude Desktop 集成（最简单）
直接安装到 Claude Desktop 以便立即使用：
# 克隆仓库
git clone https://github.com/hypersniper05/JinaWebSearchMCP.git
cd JinaWebSearchMCP
# 设置 API 密钥
export JINA_API_KEY=your_actual_api_key_here # Linux/Mac
# 或者
set JINA_API_KEY=your_actual_api_key_here # Windows
# 安装依赖并添加到 Claude Desktop
pip install -r requirements.txt
mcp install server.py --name "Jina Web Search"
选项 2：开发与测试
使用 MCP 检查器测试和调试服务器：
# 安装依赖（使用 uv - 推荐）
uv add mcp[cli] requests
# 使用 MCP 开发工具进行测试
uv run mcp dev server.py
# 或者使用 pip
pip install -r requirements.txt
mcp dev server.py
选项 3：Docker（生产环境）
# 克隆仓库
git clone https://github.com/hypersniper05/JinaWebSearchMCP.git
cd JinaWebSearchMCP
# 在 .env 文件中设置 API 密钥
cp .env.example .env
# 编辑 .env 文件并设置 JINA_API_KEY
# 使用 Docker Compose 构建并运行
docker-compose up -d
# 查看日志
docker-compose logs -f
# 停止服务器
docker-compose down
简易启动脚本：
- Windows：
run.bat或run.ps1 - Linux/Mac：
./run.sh（使用chmod +x run.sh使其可执行）
选项 4：直接执行
# 安装依赖
pip install -r requirements.txt
# 设置环境变量
export JINA_API_KEY=your_api_key_here # Linux/Mac
# 或者
set JINA_API_KEY=your_api_key_here # Windows
# 直接运行服务器
python server.py
服务器将在 http://localhost:5003 可用。
💻 使用示例
基础用法
fetch_url_content
使用 Jina AI 的爬虫服务从给定 URL 获取并返回内容。 参数：
url（字符串）：要获取内容的 URL
示例用法：
{
"name": "fetch_url_content",
"arguments": {
"url": "https://example.com"
}
}
web_search
使用 Jina AI API 执行语义网络搜索。 参数：
query（字符串）：要执行的搜索查询
示例用法：
{
"name": "web_search",
"arguments": {
"query": "latest technology news"
}
}
📚 详细文档
MCP 集成
Claude Desktop
安装后，服务器将出现在 Claude Desktop 中：
- 安装：
mcp install server.py --name "Jina Web Search" - 可用工具 将出现在 Claude 的界面中
- 自然使用：让 Claude 进行网络搜索或获取 URL 内容
- 日志：在
~/.config/claude-desktop/中查看日志
其他 MCP 客户端
此服务器可与任何 MCP 兼容的客户端配合使用：
- VS Code MCP 扩展：通过可流式 HTTP 连接
- 自定义客户端：使用官方 MCP Python SDK
- 浏览器客户端：连接到
http://localhost:5003/mcp
客户端示例：
{
"mcpServers": {
"websearch": {
"url": "http://localhost:5003/mcp"
}
}
}
Docker 详情
Docker 设置包括：
- 多阶段构建优化，以减小镜像大小
- 健康检查，用于容器监控
- 环境变量处理，用于安全的 API 密钥管理
- 自动重启策略，确保生产环境的可靠性
- 端口映射，便于访问（5003:5003）
配置
环境变量
| 属性 | 详情 |
|---|---|
JINA_API_KEY |
你的 Jina AI API 密钥，必需，默认值为 your_jina_api_key_here |
服务器配置
- 主机：
0.0.0.0（为兼容 Docker，支持所有接口） - 端口：
5003 - 传输：可流式 HTTP（现代 MCP 传输方式）
- 协议：Model Context Protocol 2025 - 06 - 18
- 框架：FastMCP（官方 Python SDK）
🔧 技术细节
本项目使用官方 Model Context Protocol Python SDK 构建，遵循 Model Context Protocol 规范。借助 Jina AI 的强大能力，实现了网络爬虫和搜索功能。项目采用多阶段 Docker 构建优化镜像大小，支持健康检查、环境变量处理、自动重启策略等，确保在生产环境中的可靠性和安全性。
📄 许可证
本项目采用 MIT 许可证 - 详情请参阅 LICENSE 文件。
致谢
- 使用官方 Model Context Protocol Python SDK 构建
- 由 Jina AI 提供网络爬虫和搜索功能支持
- 遵循 Model Context Protocol 规范
- 项目由 Qwen3 - Coder - 30B - A3B - Instruct 创建
支持
- 问题反馈：GitHub Issues
- 讨论交流：GitHub Discussions
- MCP 文档：Model Context Protocol Docs
- SDK 文档：MCP Python SDK
使用 Model Context Protocol Python SDK 精心打造 ❤️