# firecrawl/firecrawl-mcp-server architecture

> Architecture diagram of the GitHub repository firecrawl/firecrawl-mcp-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/firecrawl/firecrawl-mcp-server
- Repository: https://github.com/firecrawl/firecrawl-mcp-server

## Overview

1. **What this repo is**
   - A TypeScript **Node.js MCP server** that exposes Firecrawl web-retrieval capabilities to MCP clients.
   - It is packaged for both **stdio** execution (`npx firecrawl-mcp`) and an optional **streamable HTTP** local mode (`/mcp`).

2. **Primary runtime boundary**
   - The application entrypoint is `src/index.ts`.
   - The server sits between an MCP client (Claude Desktop, Cursor, VS Code, Windsurf, etc.) and the Firecrawl backend/API.
   - The codebase is small and focused: there are no separate frontend or database subsystems.

3. **MCP tool layer**
   - The main architecture is a **tool registry**: each MCP tool maps to a Firecrawl capability.
   - Core tool groups are:
     - single-page retrieval: `scrape`
     - multi-page retrieval: `batch_scrape`, `crawl`
     - discovery/search: `map`, `search`
     - structured extraction: `extract`
     - autonomous research: `agent`
     - browser interaction: `browser_*` legacy/deprecated tools

4. **Data flow for synchronous operations**
   - For direct requests like `scrape` or `search`, the client sends a tool call with parameters.
   - The server forwards that request to Firecrawl, transforms the response into MCP-compatible content, and returns it immediately.
   - This is the simplest request/response path and is the default for most usage.

5. **Asynchronous job flow**
   - Some operations are intentionally async because they can take a long time or produce large outputs:
     - `batch_scrape`
     - `crawl`
     - `agent`
     - some browser/session flows
   - These tools return a **job ID / operation ID** first.
   - Companion status tools (`check_batch_status`, `check_crawl_status`, `agent_status`) poll Firecrawl until the job completes and then return the final payload.

6. **External service dependency**
   - The server’s core dependency is **Firecrawl Cloud or a self-hosted Firecrawl instance**.
   - `FIRECRAWL_API_KEY` is required for cloud usage; `FIRECRAWL_API_URL` switches the server to a custom/self-hosted endpoint.
   - The repo itself does not store content; Firecrawl is the execution engine for web access, crawling, extraction, and browser automation.

7. **Transport and client integration**
   - The server is designed to be embedded in external developer tools as an MCP provider.
   - Default transport is local process I/O; a local HTTP mode is available for environments that prefer a URL-based MCP endpoint.
   - The README and `smithery.yaml` indicate multiple installer/integration targets, but they all consume the same server process.

8. **Reliability and throttling**
   - The server includes **retry/backoff configuration** and **rate-limit handling** for Firecrawl API calls.
   - Batch operations are designed with queueing/parallelism in mind, while the server limits retries and spacing via environment variables.
   - This matters architecturally because the server is not a thin proxy; it actively manages operational resilience.

9. **Monitoring and operational feedback**
   - The server emits logs for operation lifecycle, retries, and credit usage thresholds.
   - Credit monitoring is a first-class concern in the architecture because Firecrawl usage is metered and long-running jobs can consume credits quickly.
   - Errors are surfaced back through MCP responses as structured failures, not just thrown exceptions.

10. **Legacy browser subsystem**
   - The `browser_*` tools are explicitly marked **deprecated**.
   - They represent an older cloud-browser/session model and are retained for compatibility, but the preferred path is now `scrape` plus `interact`.
   - In an architecture diagram, this should be shown as a legacy branch, not the mainline flow.

11. **Repository packaging and delivery**
   - The repo is built for distribution via npm and container images.
   - `Dockerfile`, `Dockerfile.service`, and the `docker/` assets show that the server can be deployed as a containerized service as well as a CLI package.
   - GitHub Actions workflows handle CI, image builds, staging, publishing, and registry updates.

12. **Code organization signals**
   - `src/types/fastmcp.d.ts` suggests local type augmentation for the MCP runtime/library.
   - `src/legacy/index.md` indicates older documentation/behavior kept alongside the current server.
   - Tests and build tooling (`jest`, TypeScript, ESLint, Prettier) support a single-codebase service rather than a multi-package platform.

Main entry points: [`src/index.ts`](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/src/index.ts) (Server entry), [`.github/workflows/ci.yml`](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/.github/workflows/ci.yml) (CI/CD), [`Dockerfile`](https://github.com/firecrawl/firecrawl-mcp-server/tree/main/Dockerfile) (Containers), [`src/legacy/index.md`](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/src/legacy/index.md) (Browser tools)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_entrypoint["Server entry<br/>ts entrypoint<br/>[index.ts]"]
  node_tool_registry["Tool registry<br/>mcp tools"]
  node_sync_tools["Sync tools<br/>request/response"]
  node_async_tools["Async jobs<br/>job submission"]
  node_status_pollers["Status checks<br/>job polling"]
  node_response_mapper["Response mapper<br/>mcp adapter"]
end

subgraph group_integration["Integration"]
  node_mcp_client(("MCP client<br/>external client"))
  node_transport_stdio["Stdio mode<br/>mcp transport"]
  node_transport_http["HTTP mode<br/>mcp transport"]
  node_firecrawl_api[("Firecrawl API<br/>external backend")]
end

subgraph group_ops["Ops"]
  node_resilience["Retries & limits<br/>ops logic"]
  node_credit_monitor["Credit monitor<br/>ops telemetry"]
end

subgraph group_delivery["Delivery"]
  node_ci_cd["CI/CD<br/>github actions<br/>[ci.yml]"]
  node_containers["Containers<br/>docker packaging"]
  node_npm_package["NPM package<br/>cli packaging<br/>[package.json]"]
  node_build_tools["Build tools<br/>ts test lint<br/>[tsconfig.json]"]
end

subgraph group_legacy["Legacy"]
  node_legacy_browser["Browser tools<br/>deprecated tools<br/>[index.md]"]
end

node_mcp_client -->|"calls"| node_transport_stdio
node_mcp_client -->|"connects"| node_transport_http
node_transport_stdio -->|"starts"| node_entrypoint
node_transport_http -->|"starts"| node_entrypoint
node_entrypoint -->|"registers"| node_tool_registry
node_tool_registry -->|"routes"| node_sync_tools
node_tool_registry -->|"routes"| node_async_tools
node_tool_registry -.->|"includes"| node_legacy_browser
node_sync_tools -->|"formats"| node_response_mapper
node_async_tools -->|"hands off"| node_status_pollers
node_status_pollers -->|"formats"| node_response_mapper
node_sync_tools -->|"requests"| node_firecrawl_api
node_async_tools -->|"submits"| node_firecrawl_api
node_status_pollers -->|"polls"| node_firecrawl_api
node_legacy_browser -.->|"drives"| node_firecrawl_api
node_entrypoint -->|"uses"| node_resilience
node_resilience -->|"protects"| node_firecrawl_api
node_entrypoint -->|"logs"| node_credit_monitor
node_credit_monitor -->|"observes"| node_firecrawl_api
node_ci_cd -->|"builds"| node_containers
node_ci_cd -->|"publishes"| node_npm_package
node_build_tools -->|"supports"| node_entrypoint
node_containers -->|"packages"| node_entrypoint

click node_entrypoint "https://github.com/firecrawl/firecrawl-mcp-server/blob/main/src/index.ts"
click node_legacy_browser "https://github.com/firecrawl/firecrawl-mcp-server/blob/main/src/legacy/index.md"
click node_ci_cd "https://github.com/firecrawl/firecrawl-mcp-server/blob/main/.github/workflows/ci.yml"
click node_containers "https://github.com/firecrawl/firecrawl-mcp-server/tree/main/Dockerfile"
click node_npm_package "https://github.com/firecrawl/firecrawl-mcp-server/blob/main/package.json"
click node_build_tools "https://github.com/firecrawl/firecrawl-mcp-server/blob/main/tsconfig.json"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_entrypoint,node_tool_registry,node_sync_tools,node_async_tools,node_status_pollers,node_response_mapper toneBlue
class node_mcp_client,node_transport_stdio,node_transport_http,node_firecrawl_api toneAmber
class node_resilience,node_credit_monitor toneMint
class node_ci_cd,node_containers,node_npm_package,node_build_tools toneRose
class node_legacy_browser toneIndigo
```

## Components

### Runtime

MCP server execution path and tool handling

- [Server entry](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/src/index.ts): ts entrypoint · Application bootstrap and runtime wiring. · `src/index.ts`
- **Tool registry**: mcp tools · Maps MCP tool names to Firecrawl capabilities.
- **Sync tools**: request/response · Scrape, search, map, and extract paths that return immediately.
- **Async jobs**: job submission · Batch scrape, crawl, agent, and long-running browser/session flows.
- **Status checks**: job polling · check_batch_status, check_crawl_status, and agent_status.
- **Response mapper**: mcp adapter · Transforms Firecrawl payloads into MCP-compatible content and errors.

### Integration

Client transports and external Firecrawl dependency

- **MCP client**: external client · Claude Desktop, Cursor, VS Code, Windsurf, etc.
- **Stdio mode**: mcp transport · Default local process I/O server mode.
- **HTTP mode**: mcp transport · Optional streamable local HTTP endpoint.
- **Firecrawl API**: external backend · Cloud or self-hosted Firecrawl instance used for retrieval and automation.

### Ops

Resilience, logging, and credit monitoring

- **Retries & limits**: ops logic · Backoff, retry spacing, and rate-limit handling for Firecrawl calls.
- **Credit monitor**: ops telemetry · Logs usage thresholds and metered-credit warnings.

### Delivery

Packaging, images, and CI/CD

- [CI/CD](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/.github/workflows/ci.yml): github actions · Workflows for testing, images, staging, publishing, and registry updates. · `.github/workflows/ci.yml`
- [Containers](https://github.com/firecrawl/firecrawl-mcp-server/tree/main/Dockerfile): docker packaging · Dockerfile, service image, and runtime container assets. · `Dockerfile`
- [NPM package](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/package.json): cli packaging · Distributed as an installable CLI/server package. · `package.json`
- [Build tools](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/tsconfig.json): ts test lint · TypeScript, Jest, ESLint, and Prettier support for the single codebase. · `tsconfig.json`

### Legacy

Deprecated browser tooling kept for compatibility

- [Browser tools](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/src/legacy/index.md): deprecated tools · Deprecated browser/session compatibility layer. · `src/legacy/index.md`

## Connections

- MCP client → Stdio mode: calls · Client launches or attaches to the default stdio server.
- MCP client → HTTP mode: connects · Clients can also use the optional local HTTP endpoint.
- Stdio mode → Server entry: starts · stdio transport boots the server process.
- HTTP mode → Server entry: starts · HTTP transport uses the same server entrypoint.
- Server entry → Tool registry: registers · Bootstraps MCP tools and server behavior.
- Tool registry → Sync tools: routes · Direct tool calls go through the synchronous path.
- Tool registry → Async jobs: routes · Long-running operations are submitted as jobs.
- Tool registry → Browser tools: includes · Deprecated browser tools remain available for compatibility.
- Sync tools → Response mapper: formats · Maps Firecrawl responses into MCP content.
- Async jobs → Status checks: hands off · Job-based tools expose companion polling/status operations.
- Status checks → Response mapper: formats · Poll results are converted to final MCP responses.
- Sync tools → Firecrawl API: requests · Synchronous retrieval and extraction calls reach Firecrawl.
- Async jobs → Firecrawl API: submits · Async jobs are created in Firecrawl.
- Status checks → Firecrawl API: polls · Status tools query Firecrawl until completion.
- Browser tools → Firecrawl API: drives · Legacy browser/session flows still depend on Firecrawl.
- Server entry → Retries & limits: uses · Operational retry and rate-limit behavior wraps API calls.
- Retries & limits → Firecrawl API: protects · Retries, backoff, and spacing smooth API interaction.
- Server entry → Credit monitor: logs · Emits credit and lifecycle signals.
- Credit monitor → Firecrawl API: observes · Tracks metered usage implications of Firecrawl operations.
- CI/CD → Containers: builds · Workflows produce service and image artifacts.
- CI/CD → NPM package: publishes · Workflows handle package release and registry updates.
- Build tools → Server entry: supports · TypeScript and test/lint tooling support the server code.
- Containers → Server entry: packages · Container images bundle the server runtime.
