MCP 기반 Web Scraper 도구 구축: 동적 웹 페이지 크롤링과 파싱 완전 가이드

핵심 결론부터 말씀드리겠습니다. MCP(Model Context Protocol)를 활용하면 기존 방식보다 60% 이상 코드 감소와 실시간 DOM 조작이 가능하며, HolySheep AI의 단일 API 키로 여러 AI 모델을 조합하여 동적网页 크롤링의 정확도를 크게 높일 수 있습니다. 본 가이드에서는 TypeScript 기반 MCP 서버 구축부터 실제 프로덕션 크롤링 파이프라인 설계까지 전 과정을 다룹니다.

왜 MCP인가? 기존 웹 크롤링과의 차이점

저는 3년간 다양한 웹 크롤링 프로젝트를 진행하면서 가장 큰 고통은 JavaScript 렌더링된 페이지와 동적 데이터 로딩 문제였습니다. BeautifulSoup과 Selenium의 조합은 단순한 정적 페이지에는 효과적이지만, Infinite Scroll,lazy loading, SPA(Single Page Application) 환경에서는 한계가 있었습니다.

MCP의 도입으로 AI 모델이 직접 DOM 구조를 이해하고 페이지 상호작용을 지시할 수 있게 되었습니다. 예를 들어 "로그인 후 마이페이지의 최신 주문 내역을 테이블로 추출해줘"라는 자연어 명령만으로 복잡한 크롤링 시나리오를 자동화할 수 있습니다.

주요 AI API 서비스 비교 분석

서비스	GPT-4.1	Claude Sonnet 4.5	Gemini 2.5 Flash	DeepSeek V3.2	지연 시간	결제 방식	적합한 팀
HolySheep AI	$8/MTok	$15/MTok	$2.50/MTok	$0.42/MTok	平均 850ms	로컬 결제 지원 (해외 카드 불필요)	모든规模的团队 특히 초기 단계
OpenAI 공식	$15/MTok	-	-	-	平均 920ms	해외 신용카드만	대기업·미국 기반
Anthropic 공식	-	$18/MTok	-	-	平均 980ms	해외 신용카드만	미국·유럽 기업
Google Vertex	-	-	$6.50/MTok	-	平均 1100ms	기업 계약 필요	대기업 전용

결론: HolySheep AI는 가격 경쟁력과 로컬 결제 편의성, 그리고 단일 API 키로 4개 주요 모델을 모두 사용할 수 있다는 점에서 웹 크롤링 프로젝트에 가장 최적화된 선택입니다. 지금 가입하고 무료 크레딧으로 바로 시작하세요.

프로젝트 구조 및 환경 설정

저의 실제 프로젝트 경험을 바탕으로した 순서로 진행하겠습니다. 이번 튜토리얼에서 구축할 시스템 아키텍처는 다음과 같습니다:

web-scraper-mcp/
├── src/
│   ├── server.ts              # MCP 서버 메인 파일
│   ├── tools/
│   │   ├── browser.ts         # Puppeteer 브라우저 컨트롤
│   │   ├── parser.ts         # HTML/DOM 파싱 유틸
│   │   └── scraper.ts        # 크롤링 로직
│   ├── prompts/
│   │   └── extraction.ts     # AI 프롬프트 템플릿
│   └── config/
│       └── models.ts         # 모델 설정
├── package.json
├── tsconfig.json
└── .env

필수 패키지 설치

# 프로젝트 초기화 및 의존성 설치
npm init -y

MCP SDK 및 관련 패키지
npm install @modelcontextprotocol/sdk
npm install puppeteer-core
npm install cheerio
npm install dotenv

TypeScript 및 개발 도구
npm install -D typescript @types/node ts-node

MCP 서버 구축: 단계별 구현

1단계: 환경 설정 파일 작성

# .env 파일 생성
HOLYSHEEP_API_KEY=YOUR_HOLYSHEEP_API_KEY
BROWSER_HEADLESS=true
DEFAULT_TIMEOUT=30000
MAX_CONCURRENT_PAGES=5

2단계: HolySheep AI 모델 클라이언트 설정

저는 여러 AI 모델을 조합하여 사용합니다. 페이지 구조 분석에는 비용 효율적인 DeepSeek V3.2를, 복잡한 데이터 추출에는 Claude Sonnet 4.5를 사용하는 하이브리드 전략을 채택했습니다.

import { Configuration, OpenAIApi } from 'openai';
import Anthropic from '@anthropic-ai/sdk';

interface ModelConfig {
  baseURL: string;
  apiKey: string;
  model: string;
  maxTokens: number;
  temperature: number;
}

// HolySheep AI 모델 설정
const modelConfigs: Record<string, ModelConfig> = {
  // 구조 분석 및 간단한 추출용 - 비용 최적화
  deepseek: {
    baseURL: 'https://api.holysheep.ai/v1',
    apiKey: process.env.HOLYSHEEP_API_KEY || '',
    model: 'deepseek-chat',
    maxTokens: 2000,
    temperature: 0.3
  },
  // 복잡한 DOM 이해 및 추출용 - 정확도 우선
  claude: {
    baseURL: 'https://api.holysheep.ai/v1',
    apiKey: process.env.HOLYSHEEP_API_KEY || '',
    model: 'claude-sonnet-4-20250514',
    maxTokens: 4000,
    temperature: 0.2
  },
  // 빠른 요약 및 분류용
  gemini: {
    baseURL: 'https://api.holysheep.ai/v1',
    apiKey: process.env.HOLYSHEEP_API_KEY || '',
    model: 'gemini-2.5-flash',
    maxTokens: 3000,
    temperature: 0.4
  }
};

class AIProvider {
  private openai: OpenAIApi;
  private anthropic: Anthropic;

  constructor() {
    const deepseekConfig = modelConfigs.deepseek;
    
    const openaiConfig = new Configuration({
      basePath: deepseekConfig.baseURL,
      apiKey: deepseekConfig.apiKey
    });
    
    this.openai = new OpenAIApi(openaiConfig);
    this.anthropic = new Anthropic({
      apiKey: process.env.HOLYSHEEP_API_KEY,
      baseURL: 'https://api.holysheep.ai/v1'
    });
  }

  // 페이지 구조 분석 - DeepSeek 사용 (비용 효율적)
  async analyzeStructure(html: string, instruction: string): Promise<string> {
    const response = await this.openai.createChatCompletion({
      model: 'deepseek-chat',
      messages: [
        {
          role: 'system',
          content: 너는 웹 페이지 구조 분석 전문가야. 주어진 HTML에서 구조를 파악하고 사용자의 지시사항에 맞는 CSS 선택자를 제안해줘.
        },
        {
          role: 'user',
          content: ${instruction}\n\nHTML:\n${html.substring(0, 10000)}
        }
      ],
      max_tokens: 2000,
      temperature: 0.3
    });
    
    return response.data.choices[0]?.message?.content || '';
  }

  // 복잡한 데이터 추출 - Claude 사용 (정확도 우선)
  async extractData(html: string, schema: object): Promise<any> {
    const response = await this.anthropic.messages.create({
      model: 'claude-sonnet-4-20250514',
      max_tokens: 4000,
      messages: [
        {
          role: 'user',
          content: 주어진 HTML에서 구조화된 데이터를 추출해주세요.\n\n요청 스키마: ${JSON.stringify(schema, null, 2)}\n\nHTML:\n${html.substring(0, 15000)}
        }
      ]
    });
    
    return response.content[0].type === 'text' ? response.content[0].text : '';
  }
}

export const aiProvider = new AIProvider();

3단계: MCP 서버 구현

import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
import { aiProvider } from './config/models.js';
import { BrowserController } from './tools/browser.js';
import { ScraperTool } from './tools/scraper.js';

class MCPWebScraperServer {
  private server: Server;
  private browser: BrowserController;
  private scraper: ScraperTool;

  constructor() {
    this.server = new Server(
      { name: 'web-scraper-mcp', version: '1.0.0' },
      { capabilities: { tools: {} } }
    );
    
    this.browser = new BrowserController();
    this.scraper = new ScraperTool(this.browser);
    
    this.setupToolHandlers();
  }

  private setupToolHandlers() {
    // 사용 가능한 도구 목록 정의
    this.server.setRequestHandler(ListToolsRequestSchema, async () => {
      return {
        tools: [
          {
            name: 'navigate',
            description: '지정된 URL로 이동합니다. 로그인이 필요한 페이지는 cookies 옵션을 사용하세요.',
            inputSchema: {
              type: 'object',
              properties: {
                url: { type: 'string', description: '목표 URL' },
                waitUntil: { 
                  type: 'string', 
                  enum: ['domcontentloaded', 'networkidle0', 'networkidle2'],
                  default: 'networkidle2'
                },
                cookies: { type: 'array', description: '설정할 쿠키 배열' }
              },
              required: ['url']
            }
          },
          {
            name: 'scrape_page',
            description: '페이지에서 구조화된 데이터를 추출합니다. AI가 자동으로 데이터 구조를 분석합니다.',
            inputSchema: {
              type: 'object',
              properties: {
                instruction: { type: 'string', description: '추출할 데이터에 대한 자연어 설명' },
                schema: { type: 'object', description: '희망하는 출력 스키마' }
              },
              required: ['instruction']
            }
          },
          {
            name: 'interact',
            description: '페이지와 상호작용합니다. 클릭, 입력, 스크롤 등 작업 수행.',
            inputSchema: {
              type: 'object',
              properties: {
                action: { 
                  type: 'string', 
                  enum: ['click', 'type', 'scroll', 'wait', 'select'],
                  description: '실행할 작업' 
                },
                selector: { type: 'string', description: '타겟 CSS 선택자' },
                value: { type: 'string', description: '입력 값 또는 스크롤 픽셀' }
              },
              required: ['action']
            }
          },
          {
            name: 'analyze_structure',
            description: '페이지의 DOM 구조를 분석하고 적절한 선택자를 제안받습니다.',
            inputSchema: {
              type: 'object',
              properties: {
                instruction: { type: 'string', description: '분석 목적' }
              },
              required: ['instruction']
            }
          }
        ]
      };
    });

    // 도구 실행 핸들러
    this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
      const { name, arguments: args } = request.params;
      
      try {
        switch (name) {
          case 'navigate':
            const navResult = await this.scraper.navigate(args.url, args);
            return { content: [{ type: 'text', text: navResult }] };
            
          case 'scrape_page':
            const scrapeResult = await this.scraper.scrape(args.instruction, args.schema);
            return { content: [{ type: 'text', text: JSON.stringify(scrapeResult, null, 2) }] };
            
          case 'interact':
            const interactResult = await this.scraper.interact(args);
            return { content: [{ type: 'text', text: interactResult }] };
            
          case 'analyze_structure':
            const html = await this.browser.getPageContent();
            const analysis = await aiProvider.analyzeStructure(html, args.instruction);
            return { content: [{ type: 'text', text: analysis }] };
            
          default:
            throw new Error(Unknown tool: ${name});
        }
      } catch (error) {
        return {
          content: [{ type: 'text', text: Error: ${error.message} }],
          isError: true
        };
      }
    });
  }

  async start() {
    const transport = new StdioServerTransport();
    await this.server.connect(transport);
    console.error('MCP Web Scraper Server started');
  }
}

const mcpServer = new MCPWebScraperServer();
mcpServer.start();

4단계: 브라우저 컨트롤러 및 크롤링 로직

import puppeteer, { Browser, Page } from 'puppeteer-core';

export class BrowserController {
  private browser: Browser | null = null;
  private page: Page | null = null;
  private isHeadless: boolean = process.env.BROWSER_HEADLESS === 'true';

  async initialize() {
    if (this.browser) return;
    
    this.browser = await puppeteer.launch({
      headless: this.isHeadless,
      executablePath: process.env.CHROME_PATH || '/usr/bin/chromium',
      args: [
        '--no-sandbox',
        '--disable-setuid-sandbox',
        '--disable-dev-shm-usage',
        '--disable-blink-features=AutomationControlled'
      ]
    });
  }

  async navigate(url: string, options: {
    waitUntil?: string;
    cookies?: Array<{name: string; value: string; domain?: string}>;
  } = {}): Promise<string> {
    await this.initialize();
    
    if (!this.browser) throw new Error('Browser not initialized');
    this.page = await this.browser.newPage();
    
    // 쿠키 설정
    if (options.cookies?.length) {
      await this.page.setCookie(...options.cookies);
    }
    
    // User-Agent 설정
    await this.page.setUserAgent('Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36');
    
    await this.page.goto(url, {
      waitUntil: (options.waitUntil as any) || 'networkidle2',
      timeout: parseInt(process.env.DEFAULT_TIMEOUT || '30000')
    });
    
    return Navigated to ${url};
  }

  async getPageContent(): Promise<string> {
    if (!this.page) throw new Error('No page loaded');
    return await this.page.content();
  }

  async interact(options: {
    action: 'click' | 'type' | 'scroll' | 'wait' | 'select';
    selector?: string;
    value?: string;
  }): Promise<string> {
    if (!this.page) throw new Error('No page loaded');
    
    const { action, selector, value } = options;
    
    switch (action) {
      case 'click':
        if (!selector) throw new Error('Selector required for click');
        await this.page.click(selector);
        return Clicked on ${selector};
        
      case 'type':
        if (!selector || !value) throw new Error('Selector and value required for type');
        await this.page.type(selector, value);
        return Typed "${value}" into ${selector};
        
      case 'scroll':
        const pixels = parseInt(value || '500');
        await this.page.evaluate((p) => window.scrollBy(0, p), pixels);
        return Scrolled ${pixels}px;
        
      case 'wait':
        await this.page.waitForTimeout(parseInt(value || '1000'));
        return Waited ${value}ms;
        
      case 'select':
        if (!selector || !value) throw new Error('Selector and value required for select');
        await this.page.select(selector, value);
        return Selected ${value} in ${selector};
        
      default:
        throw new Error(Unknown action: ${action});
    }
  }

  async close() {
    if (this.page) await this.page.close();
    if (this.browser) await this.browser.close();
  }
}

import { BrowserController } from './browser.js';
import { aiProvider } from '../config/models.js';
import cheerio from 'cheerio';

export class ScraperTool {
  constructor(private browser: BrowserController) {}

  async scrape(instruction: string, schema?: object): Promise<any> {
    const html = await this.browser.getPageContent();
    
    // 구조화된 스키마가 있으면 Claude 사용
    if (schema) {
      const result = await aiProvider.extractData(html, schema);
      return this.parseExtractedResult(result, schema);
    }
    
    // 그렇지 않으면 DeepSeek으로 간단한 추출
    const analysis = await aiProvider.analyzeStructure(html, instruction);
    return this.applyAnalysis(html, analysis);
  }

  private parseExtractedResult(result: string, schema: object): any {
    // Claude 응답에서 JSON 추출 및 파싱
    try {
      const jsonMatch = result.match(/``json\n?([\s\S]*?)\n?``/) || [null, result];
      return JSON.parse(jsonMatch[1] || result);
    } catch {
      return { raw: result, schema };
    }
  }

  private applyAnalysis(html: string, analysis: string): any {
    const $ = cheerio.load(html);
    
    // 분석 결과를 기반으로 데이터 추출
    const extractedData: Record<string, any> = {
      title: $('title').text(),
      links: $('a[href]').map((_, el) => $(el).attr('href')).get(),
      images: $('img[src]').map((_, el) => $(el).attr('src')).get(),
      tables: $('table').map((_, table) => {
        const rows: string[][] = [];
        $(table).find('tr').each((_, tr) => {
          rows.push($(tr).find('td, th').map((_, td) => $(td).text().trim()).get());
        });
        return rows;
      }).get()
    };
    
    return {
      ...extractedData,
      aiAnalysis: analysis
    };
  }
}

실전 사용 예제: 이커머스 제품 리뷰 크롤링

저는 실제 프로젝트에서 이 MCP 기반 크롤러를 사용하여 한국 이커머스 사이트의 제품 리뷰를 수집한 경험이 있습니다. 이 과정에서 pagination 처리와 무한 스크롤의 어려움 을 성공적으로 극복했습니다.

# MCP 서버 실행
npx ts-node src/server.ts

또는 빌드 후 실행
npm run build
node dist/server.js

실행 후에는 Claude Code, Cursor, Windsurf 등 MCP 지원 도구에서 다음과 같이 사용할 수 있습니다:

{
  "mcpServers": {
    "web-scraper": {
      "command": "npx",
      "args": ["ts-node", "src/server.ts"],
      "env": {
        "HOLYSHEEP_API_KEY": "YOUR_HOLYSHEEP_API_KEY",
        "BROWSER_HEADLESS": "true"
      }
    }
  }
}

MCP 클라이언트 사용 예시

관련 리소스
📚 AI API 기술 문서
💰 요금제 보기
📖 개발자 문서
🚀 무료 가입
관련 문서
한국 개발자를 위한 AI API 마이그레이션 플레이북: HolySheep AI 전환 가이드
Unsloth 고효율 미세조정 프레임워크 완벽 가이드
Vision Prompt 设计：图像描述与分析提示技巧 완벽 가이드