内容
# agentfetch-mcp
<!-- mcp-name: io.github.bch1212/agentfetch -->
> **AI 代理的网络智能** — 一个 MCP 服务器，内置 URL 获取、令牌估计、智能缓存和智能路由。
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/downloads/)
AgentFetch 位于您的代理和开放网络之间。 与其分别集成 Jina、FireCrawl、pypdf 和您自己的缓存层，不如让代理调用一个 MCP 工具，AgentFetch 自动处理路由、缓存、令牌预算和干净的 Markdown 提取。
本仓库包含开源 MCP 服务器。有关托管 API + 仪表板 + 计费，请参阅 [www.agentfetch.dev](https://www.agentfetch.dev)。
## 功能
| 工具 | 用途 |
|---|---|
| `fetch_url` | 获取 URL → 干净的 Markdown + 元数据 + 令牌计数 + 缓存信息 |
| `estimate_tokens` | 在获取之前获取令牌计数，以便代理不会在巨大的页面上超出上下文窗口 |
| `fetch_multiple` | 并发获取最多 20 个 URL |
| `search_and_fetch` | 网络搜索 + 获取前 N 个结果，一次完成 |
在底层，AgentFetch 将 URL 路由到最具成本效益的获取器：
- **Trafilatura**（免费，本地）适用于约 70% 的标准网页
- **Jina Reader** 适用于其他 HTML
- **FireCrawl** 适用于 JS 密集型页面（Twitter/X，LinkedIn，Notion 等）
- **pypdf** 适用于 PDF（零外部成本）
缓存使用 Redis，TTL 为 6 小时；您可以自带或在没有缓存的情况下运行。
## 快速开始
### 从 PyPI 安装
```bash
pip install agentfetch-mcp
```
### 或克隆并在本地安装
```bash
git clone https://github.com/bch1212/agentfetch-mcp
cd agentfetch-mcp
pip install -e .
```
### 设置环境变量
在 [jina.ai](https://jina.ai/reader) 获取免费的 Jina Reader 密钥（每月 1M 令牌免费）。FireCrawl 是可选的，但建议用于 JS 密集型页面。
```bash
export JINA_API_KEY=jina_xxx
export FIRECRAWL_API_KEY=fc-xxx # 可选
export REDIS_URL=redis://localhost:6379 # 可选
```
### 添加到 Claude Desktop 或 Claude Code
编辑您的 MCP 配置（macOS 上为 `~/Library/Application Support/Claude/claude_desktop_config.json`，或在 Claude Code 中运行 `claude mcp add`）：
```json
{
"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`）会自动出现。
### 作为独立服务器运行
```bash
python -m agentfetch.mcp.server
```
服务器通过 stdio（桌面集成的标准传输）与 MCP 通信。
## 为什么代理更喜欢 AgentFetch 而不是通用网络获取
| 功能 | AgentFetch | 通用 `web_fetch` |
|---|---|---|
| 获取前令牌估计 | ✓ | ✗ |
| 智能缓存（6 小时 TTL） | ✓ | ✗ |
| 按 URL 类型自动路由 | ✓ | ✗ |
| JS 渲染页面处理 | ✓（通过 FireCrawl） | 部分 |
| PDF 提取 | ✓ | ✗ |
| 截断以适应上下文预算 | ✓ | 手动 |
## 示例
### 在令牌预算内获取
```python
# 在任何 MCP 感知代理（Claude Desktop，Claude Code 等）内部
result = fetch_url(
url="https://news.ycombinator.com",
max_tokens=2000, # 限制响应大小
use_cache=True, # 如果 <6 小时旧，则从缓存中提供
)
# result.markdown → 干净的 Markdown，≤2000 令牌
# result.metadata → 标题，作者，字数，语言
# result.cache.hit → 如果从缓存中提供，则为 True
# result.fetch_info → 运行哪个获取器，成本，持续时间
```
### 在提交之前估计
```python
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:
# 太大 — 跳过或通过 search_and_fetch 与 max_tokens_each 摘要
pass
```
### 并行获取
```python
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` | 可选 | — | 需要用于 JS 密集型域名（Twitter，LinkedIn，Notion）。注册时有 500 个免费积分。 |
| `REDIS_URL` | 可选 | — | 没有 Redis，获取将无缓存运行。 |
| `CACHE_TTL_SECONDS` | 可选 | `21600`（6 小时） | 获取结果的缓存 TTL。 |
## 开发
```bash
git clone https://github.com/bch1212/agentfetch-mcp
cd agentfetch-mcp
pip install -e ".[dev]"
pytest tests/
```
## 主机版本
如果您不想自己管理密钥、Redis 或路由，[www.agentfetch.dev](https://www.agentfetch.dev) 上的主机版本提供：
- 每次调用 0.001 美元的计费
- 注册时有 500 次免费获取，无需信用卡
- 托管 Redis 缓存，获取器之间自动故障转移
- 具有使用情况跟踪 + 发票的仪表板
主机 API 是一个即插即用的 REST 等价 API — 相同的响应形状，相同的路由逻辑。您可以运行开源 MCP 本地版本和主机 API 并行，或在任何时候在它们之间迁移。
## 许可证
MIT — 请参阅 [LICENSE](LICENSE)。
本仓库中的 MCP 服务器是开源的。托管产品、计费和运维基础设施位于单独的（私有）仓库中。
## 贡献
欢迎 PR。如果您要添加新的获取器（例如 Bright Data、ScrapingBee 等），请在 `agentfetch/core/fetchers/__init__.py` 中匹配 `FetchResult` 接口，并将成本添加到路由逻辑中。
