SerpApi MCP

SerpApi MCP 서버

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

기능

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

빠른 시작

SerpApi MCP 서버는 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 번들)

로컬 원클릭 설치를 위해 최신 릴리스에서 .mcpb 번들을 다운로드하고(또는 아래와 같이 빌드) Claude Desktop으로 열거나 설정 → 확장에 드롭하세요. Claude Desktop은 설치 중 SerpApi API 키를 요청하고 민감한 설정으로 저장하며 stdio를 통해 서버를 로컬에서 실행합니다. 번들은 MCPB uv 런타임을 사용합니다: 소스, pyproject.toml 및 uv.lock만 포함하며, Claude Desktop은 설치 시 uv로 Python과 고정 종속성을 프로비저닝하므로 아무것도 벤더링되지 않고 하나의 번들이 macOS, Windows 및 Linux에서 작동합니다.

uv run mcpb/build.py   # needs Node.js for the MCPB CLI; writes dist/serpapi-mcp-<version>.mcpb

번들 관련 모든 것은 mcpb/에 있으며, 프로젝트 루트에 .mcpbignore가 있습니다. 빌드는 SerpApi Playground에서 엔진 스키마를 재생성하고(--no-rebuild-engines는 작업 트리의 engines/를 대신 번들), mcpb/manifest.json을 검증하고, .mcpbignore를 제외한 git 추적 파일을 매니페스트와 함께 번들 루트에 패킹한 다음 임시 디렉토리에 설치하고 stdio를 통해 시작하여 작동하는지 확인합니다(--no-smoke는 마지막 단계를 건너뜀). 번들은 릴리스 시에만 빌드됩니다: v<version> 태그를 푸시하면 릴리스 워크플로가 실행되어 테스트 스위트를 실행한 다음 호스팅 서버를 배포하고, MCP 레지스트리 항목을 게시하고, 번들을 빌드하여 GitHub 릴리스에 첨부합니다. 풀 리퀘스트는 tests/test_mcpb.py에서 매니페스트 및 stdio 진입점 테스트를 실행하지만 번들을 패킹하지 않습니다.

동일한 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 및 앱 도구는 키가 필요하며 없으면 오류를 반환합니다.

검색 도구

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 인용 검색을 포함한 알려진 기본값과 대안을 고려합니다.

양식은 각 요청의 원래 인수에서 파생됩니다. requestState 또는 프로세스 로컬 연속 저장소를 사용하지 않으므로 공유 상태 보호 키 없이 다른 복제본에서 재시도할 수 있습니다. 인증은 모든 HTTP 요청에 적용되며 요청된 필드에 대한 답변만 사용됩니다. 답변이 다른 요구 사항을 도입하면 도구는 에이전트가 새 호출에서 제공할 나머지 필드를 나열합니다.

안내 검색을 확장하려면 엔진의 engines/<engine>.json 파일에 필수 필드, 설명, 유형 및 옵션을 추가하세요. 요구 사항이 다른 매개변수, 기본값 또는 대안에 의존하는 경우 src/engine_input_rules.py에 EngineInputRules 항목을 추가하세요. src/search_input.py의 공유 MCP 핸들러는 엔진별 분기가 필요하지 않습니다. 양식은 문자열, 숫자, 부울 및 단일 선택 필드를 지원합니다. 지원되지 않는 복잡한 필드는 누락된 매개변수 오류를 받습니다. 알 수 없는 엔진은 SerpApi로 전달됩니다.

대화형 UI(MCP 앱)

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

• search_table: 정렬 및 검색 가능한 테이블의 유기적 결과.
• search_dashboard: 요약 지표, 소스 분석 차트 및 클릭하여 확장하는 세부 패널이 있는 결과 테이블.

둘 다 search와 동일한 params을 허용합니다. MCP 앱을 지원하지 않는 호스트는 이러한 도구를 무시합니다.

MCP 호스트 없이 로컬에서 미리 보기:

uv run fastmcp dev apps src/server.py

개발

# Local development
uv sync && uv run src/server.py

# Docker
docker build -t serpapi-mcp . && docker run -p 8000:8000 serpapi-mcp

# Build the Claude Desktop extension (MCP Bundle); rebuilds engines, needs Node.js for the MCPB CLI
uv run mcpb/build.py

# Release: update pyproject.toml, server.json, mcpb/manifest.json and uv.lock together.
uv run --no-sync scripts/bump_version.py 2.0.0
# Review and commit the changes before tagging the release.
# Nothing ships on a plain push to main. The tag runs the release workflow, which runs the test
# suite and then deploys the hosted server, publishes server.json to the MCP Registry, and builds
# the MCP Bundle and attaches it to the GitHub release.
git tag v2.0.0 && git push origin v2.0.0

# Regenerate engine resources (Playground scrape)
python build-engines.py

# Testing with MCP Inspector
npx @modelcontextprotocol/inspector
# Configure: URL mcp.serpapi.com/YOUR_KEY/mcp, Transport "Streamable HTTP transport"

문제 해결

• "API 키 누락": URL 경로 /{YOUR_KEY}/mcp 또는 헤더 Bearer YOUR_KEY에 키 포함
• "잘못된 키": serpapi.com/dashboard에서 확인
• "속도 제한 초과": 대기하거나 SerpApi 요금제 업그레이드
• "결과 없음": 다른 쿼리 또는 엔진 시도

개인정보 보호정책

• 전송됨: MCP 호스트가 도구 호출에 전달하는 매개변수만. 서버는 대화의 나머지 부분, 호스트의 파일, 메모리 또는 기록을 볼 수 없습니다.
• 전달됨: 각 검색은 API 키와 함께 serpapi.com로 전송되며 결과는 변경 없이 반환됩니다. SerpApi가 검색 및 계정을 처리하는 방법은 SerpApi 개인정보 보호정책을 참조하세요.
• 보관됨: mcp.serpapi.com는 요청 메트릭(메서드, 상태 코드, 기간)을 기록하며 쿼리나 결과를 저장하지 않습니다. URL 경로의 키는 요청 로그에 나타날 수 있으므로 헤더를 선호하세요.
• 로컬 번들: Claude Desktop 확장은 사용자 머신에서 실행되며 키를 Claude Desktop 설정에 보관하고 serpapi.com를 직접 호출합니다. mcp.serpapi.com를 통과하는 것은 없습니다.
• 연락처: privacy@serpapi.com 또는 이슈 열기.

기여

1. 저장소 포크
2. 기능 브랜치 생성: git checkout -b feature/amazing-feature
3. 종속성 설치: uv install
4. 변경 사항 적용
5. 변경 사항 커밋: git commit -m 'Add amazing feature'
6. 브랜치에 푸시: git push origin feature/amazing-feature
7. 풀 리퀘스트 열기

라이선스

MIT 라이선스 - 자세한 내용은 LICENSE 파일 참조.