URL Fetch MCP

一个干净的模型上下文协议（MCP）实现，使Claude或其他大型语言模型能够从URL获取内容。

特性

• 从任何URL获取内容
• 支持多种内容类型（HTML、JSON、文本、图像）
• 对请求参数的控制（头部、超时）
• 清晰的错误处理
• 适用于Claude Code和Claude Desktop

仓库结构

url-fetch-mcp/
├── examples/               # 示例脚本和使用演示
├── scripts/                # 辅助脚本（安装等）
├── src/
│   └── url_fetch_mcp/      # 主包代码
│       ├── __init__.py
│       ├── __main__.py
│       ├── cli.py          # 命令行界面
│       ├── fetch.py        # URL获取工具
│       ├── main.py         # 核心MCP服务器实现
│       └── utils.py        # 辅助工具
├── LICENSE
├── pyproject.toml          # 项目配置
├── README.md
└── url_fetcher.py          # 用于Claude Desktop的独立启动器

安装

# 从源码安装
pip install -e .

# 安装开发依赖
pip install -e ".[dev]"

使用

运行服务器

# 使用stdio传输运行（适用于Claude Code）
python -m url_fetch_mcp run

# 使用HTTP+SSE传输运行（适用于远程连接）
python -m url_fetch_mcp run --transport sse --port 8000

在Claude Desktop中安装

有三种方式在Claude Desktop中安装：

方法1：直接安装

# 安装包
pip install -e .

# 使用包含的脚本在Claude Desktop中安装
mcp install url_fetcher.py -n "URL Fetcher"

url_fetcher.py 文件包含：

#!/usr/bin/env python
"""
URL Fetcher MCP Server

这是一个用于启动URL Fetch MCP服务器的独立脚本。
它用于通过以下命令在Claude Desktop中安装：
    mcp install url_fetcher.py -n "URL Fetcher"
"""

from url_fetch_mcp.main import app

if __name__ == "__main__":
    app.run()

方法2：使用安装脚本

# 安装包
pip install -e .

# 运行安装脚本
python scripts/install_desktop.py

scripts/install_desktop.py 脚本：

#!/usr/bin/env python
import os
import sys
import tempfile
import subprocess

def install_desktop():
    """在Claude Desktop中安装URL Fetch MCP。"""
    print("正在Claude Desktop中安装URL Fetch MCP...")
    
    # 创建一个临时Python文件，导入我们的模块
    temp_dir = tempfile.mkdtemp()
    temp_file = os.path.join(temp_dir, "url_fetcher.py")
    
    with open(temp_file, "w") as f:
        f.write("""#!/usr/bin/env python
# URL Fetcher MCP Server
from url_fetch_mcp.main import app

if __name__ == "__main__":
    app.run()
""")
    
    # 设置文件可执行权限
    os.chmod(temp_file, 0o755)
    
    # 使用文件路径运行mcp安装命令
    try:
        cmd = ["mcp", "install", temp_file, "-n", "URL Fetcher"]
        print(f"正在运行：{' '.join(cmd)}")
        
        result = subprocess.run(cmd, check=True, text=True)
        print("安装成功！")
        print("您现在可以在Claude Desktop中使用URL Fetcher工具了。")
        return 0
    except subprocess.CalledProcessError as e:
        print(f"安装过程中出现错误：{str(e)}")
        return 1
    finally:
        # 清理临时文件
        try:
            os.unlink(temp_file)
            os.rmdir(temp_dir)
        except:
            pass

if __name__ == "__main__":
    sys.exit(install_desktop())

方法3：使用CLI命令

# 安装包
pip install -e .

# 使用内置CLI命令进行安装
python -m url_fetch_mcp install-desktop

核心实现

主要的MCP实现在 src/url_fetch_mcp/main.py 中：

from typing import Annotated, Dict, Optional
import base64
import json
import httpx
from pydantic import AnyUrl, Field
from mcp.server.fastmcp import FastMCP, Context

# 创建MCP服务器
app = FastMCP(
    name="URL Fetcher",
    version="0.1.0",
    description="一个干净的MCP实现，用于从URL获取内容",
)

@app.tool()
async def fetch_url(
    url: Annotated[AnyUrl, Field(description="要获取的URL")],
    headers: Annotated[
        Optional[Dict[str, str]], Field(description="要发送的附加头部")
    ] = None,
    timeout: Annotated[int, Field(description="请求超时时间（秒）")] = 10,
    ctx: Context = None,
) -> str:
    """从URL获取内容并以文本形式返回。"""
    # 实现细节...

@app.tool()
async def fetch_image(
    url: Annotated[AnyUrl, Field(description="要获取图片的URL")],
    timeout: Annotated[int, Field(description="请求超时时间（秒）")] = 10,
    ctx: Context = None,
) -> Dict:
    """从URL获取图片并以图片形式返回。"""
    # 实现细节...

@app.tool()
async def fetch_json(
    url: Annotated[AnyUrl, Field(description="要获取JSON的URL")],
    headers: Annotated[
        Optional[Dict[str, str]], Field(description="要发送的附加头部")
    ] = None,
    timeout: Annotated[int, Field(description="请求超时时间（秒）")] = 10,
    ctx: Context = None,
) -> str:
    """从URL获取JSON，解析并以格式化形式返回。"""
    # 实现细节...

工具能力

fetch_url

从URL获取内容并以文本形式返回。

参数：

• url（必需）：要获取的URL
• headers（可选）：要发送的附加头部
• timeout（可选）：请求超时时间（秒，默认值：10）

fetch_image

从URL获取图片并以图片形式返回。

参数：

• url（必需）：要获取图片的URL
• timeout（可选）：请求超时时间（秒，默认值：10）

fetch_json

从URL获取JSON，解析并以格式化形式返回。

参数：

• url（必需）：要获取JSON的URL
• headers（可选）：要发送的附加头部
• timeout（可选）：请求超时时间（秒，默认值：10）

示例

examples 目录包含示例脚本：

• quick_test.py：MCP服务器的快速测试
• simple_usage.py：客户端API使用的示例
• interactive_client.py：用于测试的交互式CLI

# 获取URL内容的示例
result = await session.call_tool("fetch_url", {
    "url": "https://example.com"
})

# 获取JSON数据的示例
result = await session.call_tool("fetch_json", {
    "url": "https://api.example.com/data",
    "headers": {"Authorization": "Bearer token"}
})

# 获取图片的示例
result = await session.call_tool("fetch_image", {
    "url": "https://example.com/image.jpg"
})

测试

为了测试基本功能：

# 运行URL获取的直接测试
python direct_test.py

# 运行带有MCP服务器的简化测试
python examples/quick_test.py

许可证

MIT