URL Fetch MCP

一个简洁的模型上下文协议 (MCP) 实现，使 Claude 或任何 LLM 能够从 URL 获取内容。

特性

• 从任何 URL 获取内容
• 支持多种内容类型（HTML、JSON、文本、图像）
• 控制请求参数（headers、timeout）
• 简洁的错误处理
• 适用于 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 install 命令
    try:
        cmd = ["mcp", "install", temp_file, "-n", "URL Fetcher"]
        print(f"Running: {' '.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="一个用于从 URL 获取内容的简洁 MCP 实现",
)

@app.tool()
async def fetch_url(
    url: Annotated[AnyUrl, Field(description="要获取的 URL")],
    headers: Annotated[
        Optional[Dict[str, str]], Field(description="随请求发送的附加 headers")
    ] = 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="随请求发送的附加 headers")
    ] = None,
    timeout: Annotated[int, Field(description="请求超时时间（秒）")] = 10,
    ctx: Context = None,
) -> str:
    """从 URL 获取 JSON，解析它，并将其格式化后返回。"""
    # 实现细节...

工具功能

fetch_url

从 URL 获取内容并将其作为文本返回。

参数：

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

fetch_image

从 URL 获取图像并将其作为图像返回。

参数：

• url (必需): 要从中获取图像的 URL
• timeout (可选): 请求超时时间（秒）（默认值：10）

fetch_json

从 URL 获取 JSON，解析它，并将其格式化后返回。

参数：

• url (必需): 要从中获取 JSON 的 URL
• headers (可选): 随请求发送的附加 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