> Discover all available pages from the documentation index: https://mastra.zisheng.pro/ko/llms.txt

# Firecrawl을 사용한 웹 스크래핑

Firecrawl은 웹사이트를 깔끔한 마크다운이나 구조화된 JSON으로 바꾸는 웹 데이터 API입니다. 이 가이드에서는 Agent와 Workflow가 필요에 따라 라이브 웹 데이터를 검색하고 스크랩할 수 있도록 Firecrawl을 Mastra Tool에 연결합니다.

## 전제조건

- Node.js `v22.13.0` 이상 설치
- Firecrawl API 키(<https://firecrawl.dev>)
- 지원되는 [Model Provider](https://mastra.zisheng.pro/ko/models)의 API 키
- 기존 Mastra 프로젝트(새 프로젝트를 설정하려면 [설치 가이드](https://mastra.zisheng.pro/ko/guides/getting-started/quickstart)를 따르세요)

## 설치

Firecrawl SDK를 설치합니다.

**npm**:

```bash
npm install firecrawl
```

**pnpm**:

```bash
pnpm add firecrawl
```

**Yarn**:

```bash
yarn add firecrawl
```

**Bun**:

```bash
bun add firecrawl
```

## 환경 변수 구성

프로젝트 루트에 `.env` 파일을 만드세요.

```bash
FIRECRAWL_API_KEY=fc-your-api-key
# Optional: FIRECRAWL_API_URL=http://localhost:3002
```

## Firecrawl Tool 빌드

Firecrawl 검색 및 스크랩을 Mastra에 노출하는 Tool 파일을 만듭니다.

1. `src/mastra/tools/firecrawl.ts`를 만들고 Firecrawl을 설정하세요.

   ```ts
   import { Firecrawl } from 'firecrawl'
   import { createTool } from '@mastra/core/tools'
   import { z } from 'zod'

   const firecrawl = new Firecrawl({ apiKey: process.env.FIRECRAWL_API_KEY! })

   export const firecrawlSearch = createTool({
     id: 'firecrawl-search',
     description: 'Search the web and return top results.',
     inputSchema: z.object({ query: z.string().min(1) }),
     outputSchema: z.object({
       results: z.array(
         z.object({
           title: z.string().nullable(),
           url: z.string(),
         }),
       ),
     }),
     execute: async ({ query }) => {
       const results = await firecrawl.search(query, { limit: 3 })
       return {
         results: (results.web ?? []).map(item => ({
           title: item.title ?? null,
           url: item.url,
         })),
       }
     },
   })

   export const firecrawlScrape = createTool({
     id: 'firecrawl-scrape',
     description: 'Scrape a URL and return markdown content.',
     inputSchema: z.object({ url: z.string().url() }),
     outputSchema: z.object({ markdown: z.string() }),
     execute: async ({ url }) => {
       const result = await firecrawl.scrape(url, {
         formats: ['markdown'],
         onlyMainContent: true,
       })
       return { markdown: result.markdown ?? '' }
     },
   })
   ```

2. 다음에서 새 Agent를 생성하세요.`src/mastra/agents/web-agent.ts`:

   ```ts
   import { Agent } from '@mastra/core/agent'
   import { firecrawlSearch, firecrawlScrape } from '../tools/firecrawl'

   export const webAgent = new Agent({
     id: 'web-agent',
     name: 'Web Agent',
     instructions: 'Use Firecrawl tools to search and scrape web pages, then summarize the results.',
     model: 'openai/gpt-5.6-sol',
     tools: { firecrawlSearch, firecrawlScrape },
   })
   ```

3. 새로 생성한 Agent를 `src/mastra/index.ts`의 Mastra 인스턴스에 등록하세요.

   ```ts
   import { Mastra } from '@mastra/core'
   import { webAgent } from './agents/web-agent'

   export const mastra = new Mastra({
     agents: { webAgent },
   })
   ```

## 스튜디오에서 테스트

개발 서버를 실행하고 엽니다.[Studio](https://mastra.zisheng.pro/ko/docs/studio/overview):

```bash
mastra dev
```

Studio에서 **Web Agent**를 열고 다음을 시도하세요.

- "최신 Mastra 변경 로그를 찾아 마지막 릴리스를 요약합니다."
- "Firecrawl 가격을 검색하고 계획 계층을 추출합니다."

## 자체 호스팅 Firecrawl

Firecrawl을 로컬에서 실행하는 경우 `FIRECRAWL_API_URL`을 설정하거나 클라이언트에 `apiUrl`을 전달하세요.

```ts
const firecrawl = new Firecrawl({
  apiKey: process.env.FIRECRAWL_API_KEY!,
  apiUrl: process.env.FIRECRAWL_API_URL,
})
```

## 관련된

- [Firecrawl 문서](https://docs.firecrawl.dev)