Cara Membina MCP Server Web-Scraping dalam TypeScript (2026)

Model Context Protocol (MCP) ialah cara pembantu AI seperti Claude memanggil tools luaran. Jika anda mahu pembantu anda scrape web, satu pilihan ialah membina MCP server anda sendiri. Panduan ini menelusuri MCP server web-scraping yang minimum dan berfungsi dalam TypeScript -- dan jujur tentang di mana protokol itu berakhir dan di mana bahagian scraping yang sukar bermula.

Pada penghujungnya anda akan mempunyai server yang boleh dipanggil Claude, serta gambaran jelas tentang bila membina sendiri ialah langkah yang betul berbanding mengarahkan agent anda ke scraping server terurus.

Jadual Kandungan

• Apa Sebenarnya MCP Server Itu
• Prasyarat
• Langkah 1: Persediaan Projek
• Langkah 2: MCP Server Minimum
• Langkah 3: Tambah Tool Scraping Sebenar
• Langkah 4: Uji Dengan MCP Inspector
• Langkah 5: Sambungkannya ke Claude Desktop
• Bahagian Sukar: Scraping Pengeluaran
• Bina vs. Beli
• Perangkap

Apa Sebenarnya MCP Server Itu

MCP server mendedahkan tiga jenis keupayaan kepada klien AI:

• Tools -- fungsi yang dipanggil model yang melakukan kerja atau menyebabkan kesan sampingan. Tool scrape_page ialah salah satunya.
• Resources -- data baca-sahaja yang didedahkan melalui URI untuk konteks, tanpa pengiraan berat.
• Prompts -- templat mesej yang boleh diguna semula dan dicetuskan pengguna.

Untuk scraping, anda mahukan sebuah tool. Klien (Claude Desktop, Claude Code, Cursor) menunjukkan tool anda kepada model; apabila sesuatu prompt memerlukan data langsung, model mengeluarkan panggilan tool yang berstruktur, server anda menjalankannya, dan hasilnya mengalir kembali. Untuk latar belakang protokol yang lebih mendalam, lihat MCP vs REST.

Prasyarat

• Node.js 18+ (semak dengan node --version)
• Kebiasaan asas dengan TypeScript
• SDK rasmi dan sebuah pustaka schema:

npm install @modelcontextprotocol/sdk zod

Tutorial ini menyasarkan @modelcontextprotocol/sdk v1.x (kini 1.29.x), yang disarankan oleh penyelenggara untuk pengeluaran. Satu barisan v2 yang berpecah kepada @modelcontextprotocol/server dan @modelcontextprotocol/client berada dalam pre-alpha; setelah ia stabil, import akan berubah, tetapi konsep di bawah tetap terpakai.

Langkah 1: Persediaan Projek

Cipta projek dan tandakannya sebagai modul ES -- SDK ini ESM-sahaja:

// package.json
{
  "name": "scraper-mcp",
  "version": "1.0.0",
  "type": "module",
  "bin": { "scraper-mcp": "build/index.js" },
  "scripts": { "build": "tsc" }
}

Sebuah tsconfig.json minimum yang menyasarkan ES2022:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "Node16",
    "moduleResolution": "Node16",
    "outDir": "build",
    "strict": true
  },
  "include": ["src/**/*.ts"]
}

Langkah 2: MCP Server Minimum

Berikut ialah server terkecil yang mendaftarkan satu tool dan berkomunikasi dengan klien melalui stdio. Sambungan .js pada import diperlukan di bawah ESM:

// src/index.ts
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({ name: "scraper", version: "1.0.0" });

server.registerTool(
  "scrape_page",
  {
    title: "Scrape Page",
    description: "Fetch a URL and return its raw HTML",
    inputSchema: { url: z.string().url() }, // raw Zod shape, not z.object(...)
  },
  async ({ url }) => {
    const res = await fetch(url);
    const html = await res.text();
    return { content: [{ type: "text", text: html }] };
  }
);

const transport = new StdioServerTransport();
await server.connect(transport);

Itu ialah MCP server yang lengkap. API semasa ialah server.registerTool(name, config, handler); inputSchema itu ialah raw Zod shape ({ url: z.string() }), bukan z.object() yang dibungkus. Bina ia dengan npm run build.

Langkah 3: Tambah Tool Scraping Sebenar

Memulangkan raw HTML jarang berguna -- anda mahukan teks yang bersih. Tambahkan penghurai HTML:

npm install cheerio

import * as cheerio from "cheerio";

server.registerTool(
  "scrape_text",
  {
    title: "Scrape Visible Text",
    description: "Fetch a URL and return readable text, stripped of scripts and chrome",
    inputSchema: { url: z.string().url() },
  },
  async ({ url }) => {
    const res = await fetch(url, { headers: { "User-Agent": "scraper-mcp/1.0" } });
    if (!res.ok) {
      return {
        content: [{ type: "text", text: "Request failed with status " + res.status }],
        isError: true,
      };
    }
    const $ = cheerio.load(await res.text());
    $("script, style, nav, footer").remove();
    const text = $("body").text().replace(/\s+/g, " ").trim();
    return { content: [{ type: "text", text: text.slice(0, 8000) }] };
  }
);

Pulangkan isError: true apabila gagal supaya model boleh bertindak balas dan bukannya menganggap rentetan ralat sebagai kandungan halaman. cheerio menghuraikan HTML statik di sebelah server, pantas -- tetapi perhatikan apa yang ia tidak boleh lakukan, yang akan kita bincangkan di bawah.

Langkah 4: Uji Dengan MCP Inspector

Sebelum memasang apa-apa ke dalam Claude, uji secara berasingan dengan MCP Inspector:

npx @modelcontextprotocol/inspector node build/index.js

Ia membuka UI interaktif dengan tab Tools, Resources, dan Prompts. Pilih scrape_text, masukkan URL, dan jalankannya -- anda akan melihat respons serta log JSON-RPC secara langsung. Anda juga boleh menetapkan pemboleh ubah persekitaran bagi setiap server di sini, dan itulah cara anda menguji API key kemudian.

Langkah 5: Sambungkannya ke Claude Desktop

Sunting konfigurasi Claude Desktop (cipta fail itu jika ia belum wujud):

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Tambahkan server anda di bawah kunci mcpServers, menggunakan laluan mutlak ke fail yang telah dibina:

{
  "mcpServers": {
    "scraper": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/build/index.js"],
      "env": { "SCRAPER_API_KEY": "optional" }
    }
  }
}

Keluar daripada Claude Desktop sepenuhnya dan buka semula. Tool scrape_text anda kini muncul, dan anda boleh meminta Claude dalam bahasa biasa untuk scrape sesebuah halaman.

Bahagian Sukar: Scraping Pengeluaran

Kod protokol di atas ialah 20% yang mudah. Scraping dunia sebenar ialah 80% yang lain, dan tiada satu pun daripadanya khusus-MCP:

• Rendering JavaScript. cheerio hanya melihat HTML awal. Aplikasi satu-halaman me-render kandungan di sebelah klien, jadi anda memerlukan pelayar tanpa kepala seperti Playwright atau Puppeteer -- yang lambat, lapar memori, dan menyusahkan untuk pengaturan.
• Sistem anti-bot. Cloudflare, WAF, CAPTCHA, dan pengecapan jari pelayar menyekat klien HTTP yang naif. Melepasi semua itu ialah perlumbaan senjata yang berterusan.
• Proxy. Mengelak sekatan IP pada sebarang volum bermakna memutarkan kolam proxy kediaman atau pusat data.
• Had kadar, cubaan semula, dan backoff. Crawling yang bersopan dan tahan lasak memerlukan kawalan kekonkurenan dan backoff eksponen.
• Kerapuhan penghuraian. Pemilih (selector) rosak sebaik sahaja tapak sasaran menukar markupnya.

Bina vs. Beli

Bina MCP server anda sendiri untuk mempelajari protokol, atau untuk tapak dalaman yang mudah, statik, dan berkelakuan baik. Sebaik sahaja anda berdepan dengan rendering JavaScript, pertahanan anti-bot, dan putaran proxy, beban penyelenggaraan jauh mengatasi kod protokol -- itulah sebabnya kebanyakan pasukan mengarahkan agent mereka ke scraping MCP server terurus sebaliknya.

Itulah ceruk yang diisi oleh CrawlForge: 26 tools siap pakai termasuk scrape_with_actions (pelayar tanpa kepala), stealth_mode (anti-bot), batch_scrape, dan deep_research, dengan rendering JS, proxy, dan had kadar diuruskan untuk anda. Anda memasangnya dengan cara yang sama seperti server anda sendiri -- lihat menambah web scraping ke Claude Desktop -- tetapi melangkau kitaran-tanpa-henti pelayar-dan-proxy. Untuk melihat bagaimana pilihan terurus dibandingkan, lihat MCP server terbaik untuk web scraping.

Perangkap

• Jangan sekali-kali log ke stdout pada stdio server. stdout membawa strim JSON-RPC, jadi satu console.log yang tersesat akan merosakkannya dan memecahkan server. Log ke stderr dengan console.error, atau ke sebuah fail.
• Gunakan laluan mutlak dalam claude_desktop_config.json -- laluan relatif akan gagal.
• Kekal ESM: "type": "module" dalam package.json dan sambungan .js pada import SDK, dengan target: ES2022.
• Mulakan semula klien selepas sebarang perubahan konfigurasi. Gunakan Node.js 18 atau lebih baharu.
• Utamakan v1.x SDK untuk pengeluaran; anggap v2 sebagai eksperimen buat masa ini.
• Python sebaliknya? SDK Python rasmi (pakej mcp, dengan FastMCP dan dekorator @mcp.tool()) bercakap protokol yang sama dan memerlukan Python 3.10+.

Langkau penyelenggaraan -- mula percuma dengan CrawlForge dan dapatkan 26 tools scraping pengeluaran dengan 1,000 credits, tanpa kad kredit.