Firecrawl을 사용한 웹 스크래핑

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

전제조건

• Node.js v22.13.0 이상 설치
• Firecrawl API 키(https://firecrawl.dev)
• 지원되는 Model Provider의 API 키
• 기존 Mastra 프로젝트(새 프로젝트를 설정하려면 설치 가이드를 따르세요)

설치

Firecrawl SDK를 설치합니다.

npm

npm install firecrawl

pnpm

pnpm add firecrawl

Yarn

yarn add firecrawl

Bun

bun add firecrawl

환경 변수 구성

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

.env

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을 설정하세요.

   src/mastra/tools/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:

   src/mastra/agents/web-agent.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 인스턴스에 등록하세요.

   src/mastra/index.ts

   import { Mastra } from '@mastra/core'
   import { webAgent } from './agents/web-agent'
   
   export const mastra = new Mastra({
     agents: { webAgent },
   })

스튜디오에서 테스트

개발 서버를 실행하고 엽니다.Studio:

mastra dev

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

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

자체 호스팅 Firecrawl

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

src/mastra/tools/firecrawl.ts

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

관련된

• Firecrawl 문서