agentfetch

agentfetch-mcp

面向 AI Agent 的网络智能服务 — 一款内置令牌估算、智能缓存和智能路由功能的 MCP 服务，可抓取 URL。

AgentFetch 位于你的 Agent 与开放网络之间。Agent 无需分别集成 Jina、FireCrawl、pypdf 和自己的缓存层，只需调用一个 MCP 工具，AgentFetch 就会自动处理路由、缓存、令牌预算和干净的 Markdown 提取。

此代码库包含开源 MCP 服务。托管 API、仪表板和账单服务请参阅 www.agentfetch.dev。

功能

工具	用途
fetch_url	抓取 URL → 干净的 Markdown + 元数据 + 令牌数 + 缓存信息
estimate_tokens	抓取前获取令牌数，避免 Agent 因大型网页耗尽上下文窗口
fetch_multiple	并发抓取最多 20 个 URL
search_and_fetch	一次往返完成网络搜索并抓取排名前 N 的结果

在底层，AgentFetch 会将 URL 路由到成本最低且有效的抓取器：

• Trafilatura（免费、本地）适用于约 70% 的常规网页
• Jina Reader 适用于其余 HTML 页面
• FireCrawl 适用于 JavaScript 密集型页面（Twitter/X、LinkedIn、Notion 等）
• pypdf 适用于 PDF（零外部成本）

缓存使用 Redis，TTL 为 6 小时；你可以使用自己的 Redis，也可以不启用缓存。

快速开始

从 PyPI 安装

pip install agentfetch-mcp

或克隆并在本地安装

git clone https://github.com/bch1212/agentfetch-mcp
cd agentfetch-mcp
pip install -e .

设置环境变量

在 jina.ai 获取免费的 Jina Reader 密钥（免费套餐每月提供 1M 个令牌）。FireCrawl 为可选项，但建议用于 JavaScript 密集型页面。

export JINA_API_KEY=jina_xxx
export FIRECRAWL_API_KEY=fc-xxx       # optional
export REDIS_URL=redis://localhost:6379  # optional

添加到 Claude Desktop 或 Claude Code

编辑 MCP 配置（macOS 上为 ~/Library/Application Support/Claude/claude_desktop_config.json，或在 Claude Code 中运行 claude mcp add）：

{
  "mcpServers": {
    "agentfetch": {
      "command": "python",
      "args": ["-m", "agentfetch.mcp.server"],
      "env": {
        "JINA_API_KEY": "jina_xxx",
        "FIRECRAWL_API_KEY": "fc-xxx"
      }
    }
  }
}

重启 Claude。四个工具（fetch_url、estimate_tokens、fetch_multiple、search_and_fetch）会自动显示。

作为独立服务运行

python -m agentfetch.mcp.server

此服务通过 stdio 使用 MCP 通信（桌面集成的标准传输方式）。

为什么 Agent 更青睐 AgentFetch，而不是通用网页抓取工具

功能	AgentFetch	通用 web_fetch
抓取前估算令牌数	✓	✗
智能缓存（TTL 为 6h）	✓	✗
按 URL 类型自动路由	✓	✗
处理 JavaScript 渲染的页面	✓（通过 FireCrawl）	部分支持
PDF 提取	✓	✗
截断内容以适配上下文预算	✓	手动处理

示例

在令牌预算内抓取

# Inside any MCP-aware agent (Claude Desktop, Claude Code, etc.)
result = fetch_url(
    url="https://news.ycombinator.com",
    max_tokens=2000,           # cap response size
    use_cache=True,            # serve from cache if <6h old
)
# result.markdown      → clean Markdown, ≤2000 tokens
# result.metadata      → title, author, word_count, language
# result.cache.hit     → True if served from cache
# result.fetch_info    → which fetcher ran, cost, duration

抓取前进行估算

estimate = estimate_tokens(url="https://very-long-article.com")
if estimate.estimated_tokens and estimate.estimated_tokens < 5000:
    result = fetch_url(url="https://very-long-article.com")
else:
    # too big — skip or summarize via search_and_fetch with max_tokens_each
    pass

并行抓取

results = fetch_multiple(
    urls=["https://docs.python.org/3/", "https://fastapi.tiangolo.com/", ...],
    max_tokens_each=1500,
)

配置

环境变量	必需	默认值	说明
JINA_API_KEY	建议设置	—	免费套餐每月可处理约 1M 个令牌。不设置时，只能使用 Trafilatura（仍适用于约 70% 的网页）。
FIRECRAWL_API_KEY	可选	—	JavaScript 密集型域名（Twitter、LinkedIn、Notion）需要此密钥。注册后可获得 500 个免费额度。
REDIS_URL	可选	—	不使用 Redis 时，抓取结果不会缓存。
CACHE_TTL_SECONDS	可选	21600（6h）	抓取结果的缓存 TTL。

开发

git clone https://github.com/bch1212/agentfetch-mcp
cd agentfetch-mcp
pip install -e ".[dev]"
pytest tests/

托管版本

如果你不想自行管理密钥、Redis 或路由， www.agentfetch.dev 上的托管版本可提供：

• 按次付费，价格从每次抓取 $0.001 起
• 注册即可免费抓取 500 次，无需信用卡
• 托管 Redis 缓存，抓取器之间自动故障切换
• 提供使用情况跟踪和发票的仪表板

托管 API 是可直接替换的 REST 等效版本——响应格式和路由逻辑都相同。你可以同时运行本地 OSS MCP 和托管 API，也可以随时在两者之间迁移。

许可证

MIT — 详见 LICENSE。

此仓库中的 MCP 服务是开源的。托管产品、计费和运维基础设施位于另一个（私有）仓库中。

贡献

欢迎提交 PR。如果你要添加新的抓取器（例如 Bright Data、ScrapingBee 等），请遵循 agentfetch/core/fetchers/__init__.py 中的 FetchResult 接口，并在路由逻辑中添加相应成本。