> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xhuoapi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Google Search MCP 연동 가이드

> serp MCP 服务器集成

[MCP(모델 컨텍스트 프로토콜)](https://modelcontextprotocol.io)은 Anthropic에서 출시한 모델 컨텍스트 프로토콜로, AI 모델(예: Claude, GPT 등)이 표준화된 인터페이스를 통해 외부 도구를 호출할 수 있도록 합니다. XHuoAPI에서 제공하는 SERP MCP 서버를 통해 Claude Desktop, VS Code, Cursor 등 AI 클라이언트에서 직접 Google 검색을 수행하고 웹페이지, 이미지, 뉴스, 비디오, 장소 등의 검색 결과를 얻을 수 있습니다.

## 기능 개요

SERP MCP 서버는 다음과 같은 핵심 기능을 제공합니다:

* **웹 검색** — Google 웹 결과 검색
* **이미지 검색** — Google 이미지 검색
* **뉴스 검색** — Google 뉴스 검색
* **비디오 검색** — Google 비디오 검색
* **장소 검색** — Google 장소 정보 검색
* **지도 검색** — Google 지도 검색
* **다국어 다지역** — 사용자 정의 국가 및 언어 매개변수 지원
* **시간 범위 필터링** — 일, 주, 월, 년 단위로 결과 필터링

## 사전 준비

사용하기 전에 XHuoAPI API 토큰을 얻어야 합니다:

1. [XHuoAPI 플랫폼](https://api.xhuoapi.ai)에서 등록 또는 로그인
2. [Google SERP API](https://api.xhuoapi.ai/documents/serp-google) 페이지로 이동
3. 「Acquire」를 클릭하여 API 토큰을 얻기 (첫 신청 시 무료 크레딧 제공)

## 설치 구성

### 방법 1: pip 설치(추천)

```bash theme={null}
pip install mcp-serp
```

### 방법 2: 소스 코드 설치

```bash theme={null}
git clone https://github.com/XHuoAPI/SerpMCP.git
cd SerpMCP
pip install -e .
```

설치가 완료되면 `mcp-serp` 명령어로 서비스를 시작할 수 있습니다.

## Claude Desktop에서 사용하기

Claude Desktop 구성 파일을 편집합니다:

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

다음 구성을 추가합니다:

```json theme={null}
{
  "mcpServers": {
    "serp": {
      "command": "mcp-serp",
      "env": {
        "XHuoAPI_API_TOKEN": "당신의 API 토큰"
      }
    }
  }
}
```

`uvx`를 사용하는 경우(사전 설치 필요 없음):

```json theme={null}
{
  "mcpServers": {
    "serp": {
      "command": "uvx",
      "args": ["mcp-serp"],
      "env": {
        "XHuoAPI_API_TOKEN": "당신의 API 토큰"
      }
    }
  }
}
```

구성을 저장한 후 Claude Desktop을 재시작하면 대화 중에 Google 검색 관련 도구를 사용할 수 있습니다.

## VS Code / Cursor에서 사용하기

프로젝트 루트 디렉토리에 `.vscode/mcp.json`을 생성합니다:

```json theme={null}
{
  "servers": {
    "serp": {
      "command": "mcp-serp",
      "env": {
        "XHuoAPI_API_TOKEN": "당신의 API 토큰"
      }
    }
  }
}
```

또는 `uvx`를 사용할 수 있습니다:

```json theme={null}
{
  "servers": {
    "serp": {
      "command": "uvx",
      "args": ["mcp-serp"],
      "env": {
        "XHuoAPI_API_TOKEN": "당신의 API 토큰"
      }
    }
  }
}
```

## 사용 가능한 도구 목록

| 도구명                  | 설명            |
| -------------------- | ------------- |
| `serp_google_search` | Google 웹 검색   |
| `serp_google_images` | Google 이미지 검색 |
| `serp_google_news`   | Google 뉴스 검색  |
| `serp_google_videos` | Google 비디오 검색 |
| `serp_google_places` | Google 장소 검색  |
| `serp_google_maps`   | Google 지도 검색  |

## 사용 예시

구성이 완료되면 AI 클라이언트에서 자연어로 이러한 기능을 직접 호출할 수 있습니다, 예를 들어:

* 「최신 AI 논문을 검색해줘」
* 「베이징의 맛있는 훠궈 집을 검색해줘」
* 「Python 비동기 프로그래밍에 대한 이미지를 찾아줘」
* 「오늘의 기술 뉴스를 검색해줘」
* 「지도에서 근처의 카페를 찾아줘」

## 추가 정보

* GitHub 저장소: [XHuoAPI/SerpMCP](https://github.com/XHuoAPI/SerpMCP)
* PyPI 패키지: [mcp-serp](https://pypi.org/project/mcp-serp/)
* API 문서: [검색 엔진 API](https://api.xhuoapi.ai/documents/serp)