web MCP (Magico13)

Web MCP服务器

用于web搜索和URL内容检索的模型上下文协议（MCP）服务器，使用FastAPI和FastAPI-MCP构建。

特性

• 网页搜索：使用DuckDuckGo搜索网络
• URL内容检索：从任何URL获取并解析内容作为markdown

- HTML页面：转换为干净的markdown格式 - 文件：通过Goggles API从各种文件类型中提取文本（PDF、DOCX等）

本地运行

先决条件

• Python 3.13+
• 虚拟环境（推荐）

设置

# Create and activate virtual environment
python -m venv .venv
.venv\Scripts\Activate.ps1  # Windows PowerShell
# or
source .venv/bin/activate    # Linux/Mac

# Install dependencies
pip install -r requirements.txt

# Run the server
python app.py

服务器将在以下位置可用：

• APIhttp://localhost:8000
• API文件：http://localhost:8000/docs
• MCP端点：http://localhost:8000/mcp

使用Docker运行

使用Docker Compose构建和运行（推荐）

# Build and start the container
docker-compose up -d

# View logs
docker-compose logs -f

# Stop the container
docker-compose down

直接使用Docker构建和运行

# Build the image
docker build -t web-mcp-server .

# Run the container
docker run -d -p 8000:8000 --name web-mcp-server web-mcp-server

# View logs
docker logs -f web-mcp-server

# Stop the container
docker stop web-mcp-server
docker rm web-mcp-server

API终点

/search -网络搜索

使用DuckDuckGo搜索网络。

参数：

• query （字符串，必填）：搜索查询

例子：

curl "http://localhost:8000/search?query=python+programming"

/content -获取URL内容

从URL中检索和解析内容，返回带有分页支持的markdown。

参数：

• url （string，必填）：从中获取内容的URL
• offset （整数，可选）：开始的字符偏移量（默认值：0）
• limit （整数，可选）：返回的最大字符数（默认值：10000，最大值：50000）

示例：

# Get first 10,000 characters (default)
curl "http://localhost:8000/content?url=https://example.com"

# Get specific range
curl "http://localhost:8000/content?url=https://example.com&offset=10000&limit=10000"

# Get more content (up to 50,000 characters)
curl "http://localhost:8000/content?url=https://example.com&limit=50000"

响应包括分页信息：

• total：总内容长度
• returned：此响应中返回的字符
• has_more：是否有更多内容可用

MCP集成

使用以下命令将此服务器连接到任何MCP客户端（Claude Desktop、Cursor、Windsurf）：

{
  "mcpServers": {
    "web-mcp": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

配置

Goggles API端点

Goggles API端点可以通过 GOGGLES_URL 环境变量。

违约： http://localhost:8001

通过环境变量设置：

# Linux/Mac
export GOGGLES_URL=http://your-goggles-instance:8001

# Windows PowerShell
$env:GOGGLES_URL="http://your-goggles-instance:8001"

# Docker
docker run -e GOGGLES_URL=http://your-goggles-instance:8001 -p 8000:8000 web-mcp-server

# Docker Compose
# Create a .env file in the project root:
echo "GOGGLES_URL=http://your-goggles-instance:8001" > .env

Docker Hub部署

该仓库包含一个GitHub Actions工作流，当代码被推送到Docker Hub时，该工作流会自动构建Docker镜像并将其推送到Docker集线器 main 支。

设置GitHub机密和变量

要启用自动Docker Hub部署，请在GitHub存储库设置中配置以下内容：

秘密 （设置→ 秘密和变量→ 行动→ 新存储库机密）：

• DOCKER_PASSWORD：您的Docker Hub密码或访问令牌

变量 （设置→ 秘密和变量→ 行动→ 新存储库变量）：

• DOCKER_USERNAME：您的Docker Hub用户名

配置后，每次按下 main 将自动构建并推送一个标记有两者的新Docker镜像 latest 以及提交SHA。

依赖项

• fastapi-Web框架
• fastapi mcp-mcp集成
• uvicorn-ASGI服务器
• 请求-HTTP客户端
• beautifulsoup4-HTML解析
• markdownify-HTML到markdown的转换