SerpApi MCP

SerpApi MCP 서버

SerpApi와 통합하여 포괄적인 검색 엔진 결과 및 데이터 추출을 제공하는 모델 컨텍스트 프로토콜(MCP) 서버 구현체입니다.

기능

• 다중 엔진 검색: Google, Bing, Yahoo, DuckDuckGo, YouTube, eBay 및 그 외
• 엔진 리소스: MCP 리소스를 통해 엔진별 매개변수 스키마 제공 (검색 도구 참조)
• 실시간 날씨 데이터: 검색 쿼리를 통한 위치 기반 날씨 및 예보
• 주식 시장 데이터: 검색 통합을 통한 기업 재무 및 시장 데이터
• 동적 결과 처리: 다양한 결과 유형을 자동으로 감지하고 형식 지정
• 유연한 응답 모드: 전체 또는 간결한 JSON 응답
• JSON 응답: 전체 또는 간결 모드의 구조화된 JSON 출력
• 대화형 UI (MCP 앱): 지원 호스트에서 결과를 대화형 UI로 렌더링하는 선택적 search_table 및 search_dashboard 도구

빠른 시작

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

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/YOUR_SERPAPI_API_KEY/mcp

Hermes

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

Codex

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

자체 호스팅

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

인증

두 가지 방법이 지원됩니다:

• 경로 기반: /YOUR_API_KEY/mcp (권장)
• 헤더 기반: Authorization: Bearer YOUR_API_KEY

예시:

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

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

검색 도구

MCP 서버에는 모든 SerpApi 엔진과 결과 유형을 지원하는 하나의 주요 검색 도구가 있습니다. 사용 가능한 모든 매개변수는 SerpApi API 참조에서 확인할 수 있습니다. 엔진 매개변수 스키마는 MCP 리소스로도 노출됩니다: serpapi://engines (색인) 및 serpapi://engines/<engine>.

제공할 수 있는 매개변수는 각 API 엔진에 따라 다릅니다. 몇 가지 샘플 매개변수는 아래와 같습니다:

• params.q (필수): 검색 쿼리
• params.engine: 검색 엔진 (기본값: "google_light")
• params.location: 지역 필터
• mode: 응답 모드 - "complete" (기본값) 또는 "compact"
• ...기타 매개변수는 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"}}

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

결과 유형: 답변 상자, 유기적 결과, 뉴스, 이미지, 쇼핑 - 자동 감지 및 형식 지정.

대화형 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

# 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 플랜을 업그레이드하세요
• "결과 없음": 다른 쿼리나 엔진을 시도해 보세요

기여하기

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 파일을 참조하세요.