SerpApi MCP

SerpApi MCP Server

SerpApi와 통합하여 포괄적인 검색 엔진 결과와 데이터 추출을 제공하는 Model Context Protocol(MCP) 서버 구현입니다.

기능

• 다중 엔진 검색: Google, Bing, Yahoo, DuckDuckGo, YouTube, eBay 및 기타
• 엔진 리소스: MCP 리소스를 통해 엔진별 매개변수 스키마 제공(검색 도구 참조)
• 실시간 날씨 데이터: 검색 쿼리를 통한 위치 기반 날씨 및 예보
• 주식 시장 데이터: 검색 통합을 통한 기업 재무 및 시장 데이터
• 동적 결과 처리: 다양한 결과 유형을 자동으로 감지하고 형식 지정
• 유연한 응답 모드: 전체 또는 간결한 JSON 응답
• JSON 응답(기본값): 전체 또는 간결 모드의 구조화된 JSON 출력
• Markdown 응답: 평균 50%, 복잡하게 중첩된 JSON을 사용하는 API에서는 90% 이상 토큰 사용량 절감
• 대화형 UI(MCP Apps): 선택적으로 사용하는 search_table 및 search_dashboard 도구로, 지원 호스트에서 결과를 대화형 UI로 렌더링
• Claude Desktop 확장 프로그램: MCP Bundle(.mcpb)에서 한 번의 클릭으로 로컬 설치. 자세한 내용은 아래 참조

빠른 시작

SerpApi MCP Server는 mcp.serpapi.com에서 호스팅 서비스로 제공됩니다. 연결하려면 API 키를 제공해야 합니다. API 키는 SerpApi 대시보드에서 확인할 수 있습니다.

호스팅 서버를 사용하도록 Claude Desktop을 구성할 수 있습니다.

{
  "mcpServers": {
    "serpapi": {
      "type": "http",
      "url": "https://mcp.serpapi.com/YOUR_SERPAPI_API_KEY/mcp"
    }
  }
}

다음 MCP 클라이언트에도 호스팅 서버를 추가할 수 있습니다.

OpenClaw

openclaw mcp add serpapi --url https://mcp.serpapi.com/YOUR_SERPAPI_API_KEY/mcp --transport streamable-http

Claude Code

claude mcp add --transport http serpapi https://mcp.serpapi.com/mcp --header "Authorization: Bearer YOUR_SERPAPI_API_KEY"

Hermes

hermes mcp add serpapi --url https://mcp.serpapi.com/YOUR_SERPAPI_API_KEY/mcp

Codex (셸의 SERPAPI_API_KEY에서 키를 읽음)

codex mcp add serpapi --url https://mcp.serpapi.com/mcp --bearer-token-env-var SERPAPI_API_KEY

자체 호스팅

git clone https://github.com/serpapi/serpapi-mcp.git
cd serpapi-mcp
uv sync && uv run src/server.py

Claude Desktop 구성:

{
  "mcpServers": {
    "serpapi": {
      "type": "http",
      "url": "http://localhost:8000/YOUR_SERPAPI_API_KEY/mcp"
    }
  }
}

API 키 받기: serpapi.com/manage-api-key

Claude Desktop 확장 프로그램(MCP bundle)

로컬에서 한 번의 클릭으로 설치하려면 최신 릴리스에서 .mcpb bundle을 다운로드한 다음 Claude Desktop으로 열거나 Settings → Extensions에 끌어다 놓으세요. 설치 중 Claude Desktop에서 SerpApi API 키를 요청하며, 키는 민감한 설정으로 저장되고 서버는 stdio를 통해 로컬에서 실행됩니다. 설치 시 uv를 사용해 Python과 종속 항목을 준비합니다. 동일한 bundle을 macOS, Windows, Linux에서 사용할 수 있습니다.

동일한 stdio 진입점을 사용하면 서버를 하위 프로세스로 실행하는 모든 로컬 MCP 호스트에서 사용할 수 있습니다.

{
  "mcpServers": {
    "serpapi": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/serpapi-mcp", "--frozen", "--no-dev", "src/stdio.py"],
      "env": { "SERPAPI_API_KEY": "YOUR_SERPAPI_API_KEY" }
    }
  }
}

인증

다음 두 가지 방법을 지원합니다.

• 헤더 기반: Authorization: Bearer YOUR_API_KEY (권장: 키가 URL과 로그에 노출되지 않음)
• 경로 기반: /YOUR_API_KEY/mcp, 헤더를 설정할 수 없는 클라이언트용

예시:

# Header-based
curl "https://mcp.serpapi.com/mcp" -H "Authorization: Bearer your_key" -d '...'

# Path-based
curl "https://mcp.serpapi.com/your_key/mcp" -d '...'

연결, 도구 목록 조회 또는 리소스 읽기에는 키가 필요하지 않습니다. search 및 App 도구는 키가 필요하며, 키가 없으면 오류를 반환합니다.

검색 도구

MCP 서버에는 모든 SerpApi 엔진과 결과 유형을 지원하는 기본 검색 도구가 하나 있습니다. 사용 가능한 모든 매개변수는 SerpApi API 참조에서 확인할 수 있습니다. 엔진 매개변수 스키마는 MCP 리소스로도 제공됩니다. serpapi://engines(색인) 및 serpapi://engines/<engine>입니다. 인수 자동 완성을 지원하는 클라이언트는 serpapi://engines/{engine_name}에 사용할 엔진 이름 제안을 요청할 수 있습니다. 예를 들어 접두사 google_f는 일치하는 엔진 식별자를 제안합니다. 이 기능은 임의의 검색 쿼리가 아니라 리소스 URI 매개변수를 자동 완성합니다.

제공할 수 있는 매개변수는 API 엔진마다 다릅니다. 몇 가지 매개변수 예시는 다음과 같습니다.

• params.q(필수): 검색 쿼리
• params.engine: 검색 엔진(기본값: "google_light")
• params.location: 지역 필터
• params.output: 응답 형식. JSON(기본값)을 사용하려면 생략하고, Markdown을 사용하려면 "md"로 설정
• mode: 응답 모드. "compact"은 JSON에서 메타데이터를 제거하며, Markdown은 변경 없이 반환
• ...다른 매개변수는 SerpApi API 참조를 확인하세요.

예시:

{"name": "search", "arguments": {"params": {"q": "coffee shops", "location": "Austin, TX"}}}
{"name": "search", "arguments": {"params": {"q": "weather in London"}}}
{"name": "search", "arguments": {"params": {"q": "AAPL stock"}}}
{"name": "search", "arguments": {"params": {"q": "news"}, "mode": "compact"}}
{"name": "search", "arguments": {"params": {"q": "detailed search"}, "mode": "complete"}}
{"name": "search", "arguments": {"params": {"q": "news", "output": "md"}}}
{"name": "search", "arguments": {"params": {"engine": "amazon", "k": "mechanical keyboards", "amazon_domain": "amazon.com", "output": "md"}}}
{"name": "search", "arguments": {"params": {"engine": "google_scholar", "q": "retrieval augmented generation"}}}
{"name": "search", "arguments": {"params": {"engine": "youtube", "search_query": "how to make espresso"}}}
{"name": "search", "arguments": {"params": {"engine": "apple_app_store", "term": "habit tracker"}}}
{"name": "search", "arguments": {"params": {"engine": "ebay", "_nkw": "vintage mechanical keyboard"}}}

지원 엔진: Google, Bing, Yahoo, DuckDuckGo, YouTube, eBay 등(serpapi://engines 참조).

결과 유형: 답변 상자, 자연 검색 결과, 뉴스, 이미지, 쇼핑 결과를 자동으로 감지하고 형식을 지정합니다.

검색 응답은 기존 MCP structuredContent.result 문자열을 유지하며 텍스트 콘텐츠에도 동일한 문자열을 포함합니다. JSON 출력의 경우 result에 직렬화된 JSON이 포함됩니다. 기존 클라이언트는 계속해서 JSON.parse(response.structuredContent.result)로 이를 파싱할 수 있습니다. Markdown 출력에는 변경되지 않은 Markdown이 포함됩니다. 오류와 취소에도 동일한 래퍼가 사용됩니다. 검색 실행에 실패하면 isError: true가 설정됩니다. FastMCP의 상위 수준 call_tool()을 사용하는 클라이언트는 ToolError을 처리하거나, call_tool_mcp()을 사용해 결과 플래그를 확인해야 합니다. MCP 도구 결과를 참조하세요.

search는 엔진 카탈로그와 엔진별 규칙을 사용해 누락된 매개변수를 식별합니다. MCP 2026-07-28을 지원하는 클라이언트는 검색을 실행하기 전에 양식을 받습니다. 입력한 답변은 검증되며, 거부하거나 취소하면 검색이 실행되지 않습니다. 레거시 클라이언트와 양식 입력 요청을 지원하지 않는 클라이언트에는 누락된 매개변수 목록이 포함된 오류가 반환되어 에이전트가 대화에서 질문할 수 있습니다. MCP 입력 요청을 참조하세요.

• Google Flights: 출발지 및 도착지 식별자, 출발 날짜, 왕복 여행의 경우 귀국 날짜가 필요합니다. 날짜와 공항 식별자를 확인합니다. 토큰 기반 검색, 다구간 여정 및 selected_flights_json은 기존 동작을 유지합니다.
• Google Hotels: 목적지 또는 호텔 쿼리, 체크인 날짜, 체크아웃 날짜가 필요합니다. 체크아웃 날짜는 체크인 날짜 이후여야 합니다. 투숙객 수와 기타 선택적 필터는 호출자가 지정한 값이나 API 기본값을 유지합니다.
• Google Maps Directions: 누락된 출발지 및 목적지 주소가 필요합니다. 좌표나 장소 데이터 ID가 이미 제공된 경우 해당 종점은 충족된 것으로 간주합니다.
• 카탈로그의 다른 엔진도 필수 필드를 사용합니다. 예를 들어 YouTube의 search_query, Yelp의 find_loc, Amazon의 k이 있습니다. 엔진 규칙은 Amazon 카테고리 노드, eBay 카테고리, Google Scholar 인용 검색 등 알려진 기본값과 대체 항목을 고려합니다.

답변으로 인해 추가 필수 항목이 생기면 도구는 에이전트가 새 호출에서 제공해야 할 나머지 필드를 나열합니다. 양식은 문자열, 숫자, 불리언 및 단일 선택 필드를 지원합니다. 지원되지 않는 복합 필드에는 누락된 매개변수 오류가 반환됩니다. 알 수 없는 엔진은 SerpApi로 전달됩니다.

추출 도구

extract 도구는 웹 페이지를 읽고 콘텐츠를 구조화된 JSON 또는 Markdown으로 반환합니다. 단일 페이지를 추출하거나, 웹사이트의 URL을 찾거나, 여러 페이지를 크롤링할 수 있습니다. 사용 가능한 모든 매개변수는 Extract API 참조 또는 serpapi://engines/extract 리소스에서 확인하세요.

제공할 수 있는 매개변수는 다음과 같습니다.

• params.url(필수): 페이지 또는 웹사이트 URL
• params.mode: 추출 모드. "scrape"(기본값)은 단일 페이지를 읽고, "map"는 URL을 찾으며, "crawl"은 여러 페이지를 추출합니다.
• params.include_markdown: 페이지 콘텐츠를 Markdown으로 포함합니다. 스크랩 및 크롤링에서는 기본값이 true이며, 콘텐츠를 제외하려면 false으로 설정합니다.
• params.output: 응답 형식. 전체 모드에서는 기본값이 "json", 간결 모드에서는 "md"입니다. 형식을 재정의하려면 명시적으로 설정하세요.
• params.max_pages: 시작 페이지를 포함해 크롤링할 최대 페이지 수(기본값: 10, 최대: 100)
• params.json_restrictor: 반환할 필드 선택(예: "markdown,error")
• mode: 응답 모드. "complete"(기본값)은 전체 응답을 반환합니다. "compact"의 기본값은 네이티브 Markdown입니다. params.output="json"을 명시적으로 지정하면 단일 페이지 간결 추출에서 최상위 markdown 필드가 있으면 이를 유지하고 API 오류도 보존합니다. 다른 엔진으로 리디렉션된 결과를 포함해 Markdown이 없는 응답은 메타데이터를 제거한 상태로 데이터를 유지합니다. JSON을 사용할 때는 명시적으로 지정한 params.json_restrictor 값과 params.include_markdown=false이 우선 적용됩니다. 지도 및 크롤링의 경우 간결 JSON에서 메타데이터가 제거됩니다. Markdown 출력은 변경 없이 반환됩니다.

예시:

{"name": "extract", "arguments": {"params": {"url": "https://example.com"}}}
{"name": "extract", "arguments": {"params": {"url": "https://example.com"}, "mode": "compact"}}
{"name": "extract", "arguments": {"params": {"url": "https://example.com", "output": "md"}}}
{"name": "extract", "arguments": {"params": {"url": "https://example.com", "mode": "map"}}}
{"name": "extract", "arguments": {"params": {"url": "https://example.com", "mode": "crawl", "max_pages": 2}}}

단일 페이지 콘텐츠를 네이티브 Markdown으로 받으려면 mode="compact"을 사용하세요. 대신 params.output="json"을 추가하면 markdown 필드가 포함된 JSON을 받을 수 있습니다. 전체 JSON에는 기본적으로 해당 필드가 포함되며, 크롤링 JSON에서는 각 pages 항목에 포함됩니다. params.output="json"과 params.include_markdown=false를 설정하면 Markdown 없이 나머지 구조화된 필드를 유지합니다.

캐시되지 않은 요청에서 크롤링은 성공적으로 추출된 페이지마다 검색 크레딧을 하나씩 사용합니다. 추출할 페이지 수를 제한하려면 params.max_pages을 사용하세요.

대화형 UI(MCP apps)

search 도구는 기본적으로 JSON을 반환합니다. MCP Apps 확장(SEP-1865)을 지원하는 호스트에서는 선택적으로 사용하는 두 도구가 결과를 대화에 직접 대화형 UI로 렌더링하므로, 대량의 SERP JSON이 모델의 컨텍스트 창에 들어가지 않습니다.

• search_table: 자연 검색 결과를 정렬 및 검색 가능한 표로 표시합니다.
• search_dashboard: 요약 지표, 출처별 분석 차트, 클릭해 펼칠 수 있는 세부 정보 패널이 포함된 결과 표를 표시합니다.

두 도구 모두 search과 동일한 params을 받습니다. MCP Apps를 지원하지 않는 호스트는 이 도구를 무시합니다.

문제 해결

• "Missing API key": URL 경로 /{YOUR_KEY}/mcp 또는 헤더 Bearer YOUR_KEY에 키를 포함하세요.
• "Invalid key": serpapi.com/dashboard에서 확인하세요.
• "Rate limit exceeded": 잠시 기다리거나 SerpApi 요금제를 업그레이드하세요.
• "No results": 다른 쿼리나 엔진을 사용해 보세요.

개인정보 처리방침

• 전송되는 정보: MCP 호스트가 도구 호출에 전달하는 매개변수만 전송됩니다. 서버는 호스트의 나머지 대화 내용이나 파일, 메모리 또는 기록을 볼 수 없습니다.
• 전달되는 정보: 각 검색은 API 키와 함께 serpapi.com로 전송되며, 결과는 변경 없이 반환됩니다. SerpApi가 검색 및 계정을 처리하는 방식은 SerpApi 개인정보 처리방침을 참조하세요.
• 보관되는 정보: mcp.serpapi.com는 요청 지표(메서드, 상태 코드, 소요 시간)를 기록하며 쿼리나 결과는 저장하지 않습니다. URL 경로에 포함된 키는 요청 로그에 나타날 수 있으므로 헤더 사용을 권장합니다.
• 로컬 bundle: Claude Desktop 확장 프로그램은 사용자 컴퓨터에서 실행되며, 키를 Claude Desktop 설정에 보관하고 serpapi.com을 직접 호출합니다. mcp.serpapi.com를 거치는 정보는 없습니다.
• 문의: privacy@serpapi.com으로 문의하거나 이슈를 등록하세요.

기여

개발 환경 설정, 스키마 새로 고침 명령, 테스트, Docker 및 MCP Bundle 빌드, 릴리스에 대한 내용은 CONTRIBUTING.md를 참조하세요.

라이선스

MIT License입니다. 자세한 내용은 LICENSE 파일을 참조하세요.