Skip to main content
Glama
tavily-firecrawl-mcp

tavily-firecrawl-mcp

by bpzx

tavily-firecrawl-mcp

一个用于网页抓取和搜索的 MCP(Model Context Protocol)服务器。

  • web_fetch —— 把网页正文提取为 Markdown(或纯文本)。以 Tavily Extract 为主用,失败或返回空时自动回退到 Firecrawl Scrape。

  • web_search —— 搜索网页,返回标题、URL、摘要(Tavily 可选合成答案)。以 Tavily Search 为主用,可重试错误自动回退到 Firecrawl Search。

API key 从环境变量读取。未配置 key 的 provider 会被直接跳过,不会向它发起任何请求。

适用场景

  • 抓取单个网页的正文内容(博客、文档、新闻等)。

  • 当主用服务(Tavily)不可用时,自动用备用服务(Firecrawl)兜底,提高可用性。

  • 用 Tavily 做联网搜索,获取最新信息。

Related MCP server: OneSearch MCP Server

环境要求

  • Python ≥ 3.11

  • Tavily API key(TAVILY_API_KEY)

  • 可选:Firecrawl API key(FIRECRAWL_API_KEY),用于抓取/搜索回退。不配则仅用 Tavily。

运行方式

本服务用 Python 实现,推荐用 uvx(uv 的命令运行器)运行 —— 无需全局安装、自动隔离环境。

方式一:uvx(推荐)

无需 pip install,直接运行。两种来源:

# 已发布到 PyPI 时
uvx tavily-firecrawl-mcp

# 或者直接从 git 仓库运行
uvx --from "git+https://github.com/bpzx/tavily-firecrawl-mcp" tavily-firecrawl-mcp

uvx 会根据 pyproject.toml 的 [project.scripts] 入口点(tavily-firecrawl-mcp = tavily_firecrawl_mcp.server:main)找到并运行服务。首次运行会自动创建隔离环境并安装依赖。

方式二:本地 pip 安装

在本目录下:

pip install -e .

然后即可通过命令 tavily-firecrawl-mcp 或 python -m tavily_firecrawl_mcp 启动。

调试 / 检查

用官方 MCP Inspector 可视化调试:

npx @modelcontextprotocol/inspector uvx tavily-firecrawl-mcp

配置 API key

在环境(或 MCP 客户端加载的 .env)中设置:

export TAVILY_API_KEY=tvly-xxxxxxxxxxxx
export FIRECRAWL_API_KEY=fc-xxxxxxxxxxxx   # 可选

仓库内附 .env.example。

出站代理(可选)

当 Tavily / Firecrawl 的 API 端点在你的网络下无法直连或不稳定(例如国内网络),可通过 WEB_FETCH_PROXY 指定本地代理:

export WEB_FETCH_PROXY=http://127.0.0.1:7890

设置 WEB_FETCH_PROXY 后它优先级最高,并禁用 httpx 的环境变量回退;未设置时,httpx 仍会读取标准的 HTTP_PROXY / HTTPS_PROXY / ALL_PROXY 环境变量。若这些环境变量里存在 httpx 无法解析的值(例如 NO_PROXY 中的 IPv6 写法 [::1]),服务会降级为直连并在日志中告警,而不是崩溃。

自托管端点(可选)

Firecrawl 支持自托管。如需将请求指向私有部署,设置对应的 base URL(值末尾的 / 会被自动去掉):

export FIRECRAWL_BASE_URL=https://firecrawl.internal.example.com
export TAVILY_BASE_URL=https://tavily-proxy.internal.example.com   # 如需代理 Tavily 端点

工具

web_fetch(url, ...)

参数

类型

默认值

说明

url

str

必填

要抓取的页面 URL。

query

str | None

None

Tavily 会按该意图对提取内容重排。

format

"markdown" | "text"

"markdown"

输出格式。

extract_depth

"basic" | "advanced"

"basic"

Tavily 提取深度。

only_main_content

bool

True

仅 Firecrawl 生效 —— 去掉导航/广告/页脚。

timeout

int

30

单次请求超时,单位秒。

返回 { ok, url, provider, content, format, used_fallback, failed_providers, metadata }。 当结果由 Firecrawl 在 Tavily 失败后产出时,used_fallback 为 true。

web_search(query, ...)

参数

类型

默认值

说明

query

str

必填

搜索词。

max_results

int

5

结果数量(1–20)。

search_depth

"basic" | "advanced"

"basic"

仅 Tavily;advanced 更慢但更深入。

topic

"general" | "news"

"general"

仅 Tavily;切换为新闻搜索。

include_answer

bool

False

仅 Tavily;是否同时返回合成答案。

返回 { ok, query, provider, used_fallback, failed_providers, answer, results: [{title, url, content, score}] }。 answer 仅由 Tavily 产生(Firecrawl 无答案合成);当结果由 Firecrawl 在 Tavily 失败后产出时,used_fallback 为 true。

回退机制说明

web_fetch 与 web_search 都按顺序遍历 provider 链:Tavily → Firecrawl。

  1. 若 Tavily 已配置且返回非空结果 → 直接返回。

  2. 若 Tavily 因可重试错误(auth、限流、5xx、网络、空内容)失败且 Firecrawl 已配置 → 尝试 Firecrawl,标记 used_fallback: true,并把 Tavily 的失败记录写入 failed_providers。

  3. 不可重试错误(如 404)会立即抛出,不尝试备用。

  4. 所有 provider 都失败或都未配置时,工具返回 ok: false 及结构化的 failures 列表,便于调用方处理。

未配置 key 的 provider 不会出现在链中,因此只配一个 key 即可实现 Tavily-only 或 Firecrawl-only。

客户端配置

Claude Desktop / Claude Code(claude_desktop_config.json)

{
  "mcpServers": {
    "tavily-firecrawl": {
      "command": "uvx",
      "args": ["tavily-firecrawl-mcp"],
      "env": {
        "TAVILY_API_KEY": "tvly-xxxxxxxxxxxx",
        "FIRECRAWL_API_KEY": "fc-xxxxxxxxxxxx",
        "WEB_FETCH_PROXY": "http://127.0.0.1:7890"
      }
    }
  }
}

通用 stdio 客户端

{
  "command": "uvx",
  "args": ["tavily-firecrawl-mcp"]
}

确保服务端继承的环境中已导出 TAVILY_API_KEY(以及可选的 FIRECRAWL_API_KEY / WEB_FETCH_PROXY)。

日志与诊断

服务通过 stdio 传输运行:stdout 仅承载 JSON-RPC,所有诊断日志写入 stderr。日志级别可通过 LOG_LEVEL 环境变量调整(默认 INFO):

export LOG_LEVEL=DEBUG

开发

pip install -e ".[dev]"
pytest
ruff check src tests
mypy src

许可证

MIT

Available Tools

2 tools
web_fetchA

Fetch and extract the content of a web page as markdown (or plain text). Tries Tavily first; on failure or empty result, automatically falls back to Firecrawl. Requires TAVILY_API_KEY and/or FIRECRAWL_API_KEY in the server's environment.

Inputs: url (required), query, format, timeout, +2 more. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 2 tools

    Disambiguation5/5

    web_search (discovery of titles/URLs/snippets) and web_fetch (retrieval of full page content) are clearly distinct actions on different outputs. There is no plausible scenario where an agent would confuse which one to call first.

    Naming Consistency5/5

    Both tools follow an identical 'web_<verb>' snake_case pattern, making the naming perfectly predictable. Adding a third tool would be trivially guessable (e.g., web_crawl).

    Tool Count4/5

    Two tools is slightly below the typical 3-15 sweet spot, but for a focused web-access server each tool earns its place and there is no filler. The scope is intentionally minimal rather than padded.

    Completeness4/5

    Search plus fetch covers the core read-only lifecycle of web access, including provider fallback for reliability. Minor gaps exist (no crawl/site-mapping, no batch or structured extract), but agents can work around these by chaining search into fetch.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers