mcp-web-search

인터넷 검색을 위한 MCP(Model Context Protocol) 서버로, Vercel에 stateless HTTP API로 배포됩니다. Antigravity와 같은 AI 에이전트가 웹을 검색하고, 페이지를 읽고, REST API를 사용하고, 링크를 추출할 수 있게 해줍니다 — 안티봇 차단 문제 없이.

사용 가능한 도구

Related MCP server: Spider MCP Server

스택

• Next.js 16 (App Router) — 서버 프레임워크

• mcp-handler — MCP 프로토콜용 HTTP 어댑터

• @modelcontextprotocol/server — MCP SDK v2

• Tavily API — 공식 검색 및 페이지 추출 엔진(안티봇 차단에 면역)

• axios + cheerio + turndown — REST API 사용 및 HTML 콘텐츠 파싱

• Zod v4 — 도구 스키마 검증

• Vercel Hobby — 무료 호스팅(요청당 60초 타임아웃)

Tavily API 설정

Vercel 및 기타 데이터센터는 웹 콘텐츠를 스크래핑하려고 할 때 방화벽에 의해 자주 차단되므로, 이 프로젝트는 Tavily를 사용합니다. Tavily는 페이지를 읽고 인터넷을 100% 안정적으로 검색할 수 있는 AI 특화 API입니다.

완벽하게 작동하려면:

1. tavily.com에서 무료 계정을 만드세요(월 1,000회 무료 요청 제공).

2. 호스팅 패널(예: Vercel)에서 다음 환경 변수를 추가하세요:

   • TAVILY_API_KEY: sua_chave_aqui

Vercel에 배포

사전 요구 사항

• Node.js 20+

• pnpm

1. 저장소 클론

git clone https://github.com/suportebono/mcp-web-search.git
cd mcp-web-search
pnpm install

2. 로컬에서 테스트

pnpm dev

MCP 엔드포인트는 http://localhost:3000/api/mcp에서 사용할 수 있습니다.

도구를 시각적으로 검사하려면:

npx @modelcontextprotocol/inspector http://localhost:3000/api/mcp

3. Vercel에 게시

npx vercel

배포 후 https://mcp-web-search-xxx.vercel.app 형식의 URL을 받게 됩니다. TAVILY_API_KEY를 설정하는 것을 잊지 마세요!

Antigravity에서 설정

~/.gemini/config/mcp_config.json 파일을 편집하세요(없으면 생성):

{
  "mcpServers": {
    "web-search": {
      "serverUrl": "https://seu-projeto.vercel.app/api/mcp"
    }
  }
}

Antigravity를 다시 시작하고 **... > MCP Servers**에서 확인하세요. 4개의 도구가 목록에 표시되어야 합니다.

다른 MCP 클라이언트에서 설정

Claude Desktop / Cursor / Windsurf

클라이언트 구성 파일에 추가하세요:

{
  "mcpServers": {
    "web-search": {
      "url": "https://seu-projeto.vercel.app/api/mcp"
    }
  }
}

stdio만 지원하는 클라이언트

mcp-remote 패키지를 프록시로 사용하세요:

{
  "mcpServers": {
    "web-search": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://seu-projeto.vercel.app/api/mcp"]
    }
  }
}

도구 참조

web_search

Tavily API를 사용하여 인터넷을 검색합니다.

매개변수:

반환 예시:

[
  {
    "title": "Next.js 15 — Blog",
    "url": "https://nextjs.org/blog/next-15",
    "snippet": "Next.js 15 introduces...",
    "source": "nextjs.org"
  }
]

read_webpage

Tavily Extract를 사용하여 페이월과 안티봇을 우회하고 URL의 콘텐츠를 읽고 추출합니다.

매개변수:

콘텐츠를 반환하기 전에 스크립트, 스타일, 광고, 내비게이션, 푸터를 자동으로 제거합니다.

fetch_json

Axios를 통해 GET 요청을 보내고 원시 JSON을 반환합니다.

매개변수:

extract_links

Tavily Extract를 사용하여 페이지의 실제 HTML(동적 사이트 포함)을 읽고 모든 링크를 추출합니다.

매개변수:

반환 예시:

[
  {
    "text": "Documentação",
    "href": "/docs",
    "absolute_url": "https://exemplo.com/docs"
  }
]

프로젝트 구조

mcp-web-search/
├── app/
│   └── api/
│       └── mcp/
│           └── route.ts        ← Endpoint MCP (GET + POST)
├── lib/
│   ├── mcp-server.ts           ← Registro de todas as ferramentas
│   └── tools/
│       ├── web-search.ts       ← Busca via Tavily API
│       ├── read-webpage.ts     ← Leitura e parsing de páginas (Tavily Extract)
│       ├── fetch-json.ts       ← Fetch de APIs REST genéricas
│       └── extract-links.ts    ← Extração de links via Tavily Extract HTML
├── next.config.ts
└── package.json

지원되는 MCP 프로토콜

이 서버는 Streamable HTTP stateless 전송을 통해 MCP 2026-07-28 사양을 구현하며 최신 클라이언트와 호환됩니다. 또한 2025년형 Streamable HTTP 사양을 사용하는 클라이언트를 위한 자동 폴백도 제공합니다.

라이선스

MIT