# Claude Desktop, Cursor 및 기타 MCP 클라이언트용 Google 검색 MCP 서버

> Claude Desktop, Claude Code, Cursor 및 기타 MCP 클라이언트에 Google 검색을 추가하세요: SerpCrypto SERP API를 사용하는 40줄짜리 Python MCP 서버입니다. KYC 없이, 암호화폐 결제.

- URL: https://serpcrypto.com/ko/docs/mcp/
- 마지막 업데이트: 2026-10-22
- 발행자: SerpCrypto (https://serpcrypto.com)

모든 MCP 클라이언트에 실시간 Google 검색 결과를 반환하는 `google_search` 도구를 제공하세요. 서버는 직접 실행하는 Python 파일 하나이며, SerpCrypto API를 호출해 모델이 읽을 수 있는 간결한 텍스트를 반환합니다.

**빠른 답변 — MCP 서버로 Claude Desktop이나 Cursor에 Google 검색을 추가하려면 어떻게 하나요?**

아래 40줄짜리 Python 서버를 저장하고 `mcp[cli]`와 `httpx`을 설치한 뒤, 클라이언트의 MCP 설정에서 **SerpCrypto** API 키를 `env`에 넣어 등록하세요. 그러면 클라이언트는 실시간 Google 검색 결과를 반환하는 `google_search` 도구를 갖게 됩니다. 도구 호출 한 번은 US$0.30/1K 검색에서의 검색 한 번으로 1 크레딧이며, 크레딧은 KYC 없이 암호화폐로 결제합니다.

## MCP 서버 한눈에 보기

| 속성 | 값 |
| --- | --- |
| 언어 | 공식 `mcp` SDK(FastMCP)와 `httpx`을 사용하는 Python 3.10+ |
| 전송 | stdio: 클라이언트가 스크립트를 시작하고 통신합니다 |
| 도구 | `google_search(query, gl, hl, num_results)` |
| 출력 | AI Overview 텍스트(표시되는 경우), 그다음 결과별 제목, 링크, 스니펫 |
| 키 | 클라이언트 설정에 지정하는 환경 변수 `SERPCRYPTO_API_KEY` |
| 비용 | 성공한 도구 호출당 1 크레딧, 오류는 무료 |

## 서버는 무엇을 하나요?

Model Context Protocol을 통해 `google_search`라는 도구 하나를 제공합니다. 모델이 이 도구를 호출하면 서버가 `https://serpcrypto.com/api/v1/search`에 요청 하나를 보낸 뒤 JSON을 짧은 일반 텍스트로 변환합니다: Google이 AI Overview를 보여줬다면 그 내용과, 상위 결과의 제목, 링크, 스니펫입니다.

짧은 텍스트가 중요합니다. JSON으로 된 전체 결과 페이지는 길고, 모델로 돌려보내는 모든 문자는 컨텍스트를 사용합니다. 서버는 최대 10개의 결과를 유지하고 AI Overview는 800자에서 자릅니다. 클라이언트에 여유가 있다면 코드에서 이 제한을 변경하세요.

이것은 복사-붙여넣기용 코드이며 배포된 패키지가 아닙니다: 설치할 공식 SerpCrypto MCP 패키지는 없습니다. 파일은 직접 소유하며, 예를 들어 `engine=google_news`용 도구를 추가할 수 있습니다.

*serpcrypto_mcp.py*

```python
"""serpcrypto_mcp.py: an MCP server that gives AI clients a Google search tool.

Install once:  pip install "mcp[cli]" httpx
Run by your MCP client over stdio; the API key comes from the environment.
"""
import os

import httpx
from mcp.server.fastmcp import FastMCP

API_URL = "https://serpcrypto.com/api/v1/search"
mcp = FastMCP("serpcrypto-search")


@mcp.tool()
async def google_search(query: str, gl: str = "us", hl: str = "en", num_results: int = 5) -> str:
    """Search Google and return the top results (title, link, snippet) and the AI Overview text if any.

    gl is a two-letter country code (us, gb, de...), hl a language code (en, de, pt-BR...).
    Each call uses one SerpCrypto search credit.
    """
    headers = {"Authorization": "Bearer " + os.environ["SERPCRYPTO_API_KEY"]}
    params = {"q": query, "gl": gl, "hl": hl}
    async with httpx.AsyncClient(timeout=90) as client:
        r = await client.get(API_URL, params=params, headers=headers)
    if r.status_code != 200:
        return f"Search failed with HTTP {r.status_code}: {r.text[:300]}"
    data = r.json()
    lines = []
    overview = data.get("ai_overview") or {}
    if overview.get("text"):
        lines.append("AI Overview: " + overview["text"][:800])
    for item in data.get("organic_results", [])[: max(1, min(num_results, 10))]:
        lines.append(f"{item['position']}. {item['title']}\n{item['link']}\n{item.get('snippet', '')}")
    return "\n\n".join(lines) or "No results."


if __name__ == "__main__":
    mcp.run()  # stdio transport
```

## 도구 이름이 web_search가 아니라 google_search인 이유는 무엇인가요?

여러 클라이언트가 이미 자체 제공자를 사용하는 `web_search`라는 이름의 도구를 제공합니다. 이름을 다르게 하면 충돌을 피하고 모델에 무엇을 받는지 알려줍니다: 모델이 선택한 국가와 언어에 대한 Google 검색 결과입니다. docstring은 모델이 읽는 설명이므로, 여기에 파라미터와 호출 비용을 명시합니다.

## Claude Desktop에 추가하려면 어떻게 하나요?

설정 파일 `claude_desktop_config.json`을 여세요: macOS에서는 `~/Library/Application Support/Claude/`에, Windows에서는 `%APPDATA%\Claude\`에 있습니다. `mcpServers` 아래에 서버를 추가하고 스크립트의 절대 경로와 `env`에 키를 넣은 뒤 Claude Desktop을 재시작하세요.

Claude Desktop이 인식하는 경로에 `python`이 없다면 인터프리터의 전체 경로를 사용하세요. 예를 들어 가상 환경 내부의 경로를 사용하면 됩니다.

*claude_desktop_config.json*

```json
{
  "mcpServers": {
    "serpcrypto-search": {
      "command": "python",
      "args": ["/absolute/path/to/serpcrypto_mcp.py"],
      "env": {
        "SERPCRYPTO_API_KEY": "paste-your-key-here"
      }
    }
  }
}
```

## Claude Code와 Cursor에 추가하려면 어떻게 하나요?

Claude Code에서는 터미널에서 `claude mcp add`로 등록합니다. `-e`는 환경 변수를 설정하고, `--` 뒤에 오는 모든 내용이 실행할 명령입니다. Cursor에서는 위와 동일한 `mcpServers` 블록을 모든 프로젝트에 적용하려면 `~/.cursor/mcp.json`에, 프로젝트 하나에만 적용하려면 `.cursor/mcp.json`에 넣습니다.

stdio 서버를 실행하는 다른 MCP 클라이언트도 같은 세 가지를 받습니다. 명령, 인수, 환경 변수입니다. [OpenClaw 페이지](https://serpcrypto.com/ko/docs/openclaw/)에 OpenClaw용 명령이 나와 있습니다.

*Claude Code*

```bash
claude mcp add serpcrypto-search \
  -e SERPCRYPTO_API_KEY=paste-your-key-here \
  -- python /absolute/path/to/serpcrypto_mcp.py
```

## API 키는 어떻게 안전하게 보관하나요?

클라이언트 설정의 `env` 블록이나 셸 프로필에 보관하고, `serpcrypto_mcp.py` 안에는 절대 넣지 마세요. 그래야 키 없이 스크립트를 공유하거나 커밋할 수 있습니다. 키가 유출되면 대시보드에서 폐기하고 새로 만드세요: 대시보드에서 언제든지 생성하고 폐기할 수 있는 API 키.

MCP 서버에는 전용 키를 발급하세요. 그러면 키별 사용량에서 스크립트와 별도로 어시스턴트가 몇 번 검색하는지 확인할 수 있습니다.

## 어시스턴트는 크레딧을 얼마나 사용하나요?

성공한 툴 호출마다 1크레딧입니다. 모델이 세 번 검색하는 채팅은 3크레딧입니다. US$18.75의 검색 25,000회 팩이라면 수천 건의 어시스턴트 질문에 해당하고, 선불 검색 크레딧은 만료되지 않습니다: 사용하지 않은 검색은 사용할 때까지 계정에 남아 있습니다.

사용량을 제한하려면 `num_results`을 낮추세요(가격은 그대로지만 답변이 짧아집니다). 그리고 지침에서 모델에게 최신 정보가 필요할 때만 검색하라고 알려주세요.

## MCP 질문

### 서버가 원격 MCP 클라이언트와도 작동하나요?

이 버전은 stdio를 사용하므로 클라이언트가 같은 머신에서 실행해야 합니다. FastMCP는 HTTP로도 서비스할 수 있습니다. 네트워크에 노출한다면 반드시 앞단에 인증을 두세요. 접근할 수 있는 사람은 누구나 여러분의 크레딧을 사용하기 때문입니다.

### Bing이나 Google News로도 검색할 수 있나요?

네. `engine` 인수를 추가하거나, `params`에 `engine=bing` 또는 `engine=google_news`를 보내는 두 번째 툴을 추가하세요. 모든 엔진은 검색당 동일하게 1크레딧입니다.

### 클라이언트에서 툴이 실패했다고 나오는 이유는 무엇인가요?

같은 Python으로 스크립트를 직접 실행해 오류를 확인하세요. 흔한 원인은 `mcp` 또는 `httpx` 패키지 누락, 설정의 잘못된 경로, 비어 있는 `SERPCRYPTO_API_KEY`(API가 `401`를 응답합니다)입니다.

### API 키 발급에 신용카드나 KYC가 필요한가요?

아니요. SerpCrypto는 BTC, USDT, USDC, ETH, SOL, LTC로 결제하는 선불 크레딧을 판매하며, 신분증도 셀피도 서류도 필요 없습니다. 계정 번호로 로그인하며 이메일은 선택 사항입니다.

---

SerpCrypto: SerpCrypto는 개발자와 AI 에이전트를 위한 SERP API로, Google 및 Bing 검색 결과를 JSON으로 반환하며 신분증 업로드 없이 암호화폐로 결제합니다. 선불 검색 크레딧 US$0.30/1K 검색는 만료되지 않습니다. KYC 없이 — 신분증도, 셀피도, 서류도 없습니다. 암호화폐 결제.