Google 검색 MCP 서버

Google의 맞춤 검색 API를 통해 웹 및 이미지 검색 기능을 제공하는 모델 컨텍스트 프로토콜(MCP) 서버입니다. 이 서버는 Claude 및 기타 AI 비서와 통합하기 위해 MCP 사양을 따릅니다.

우리가 무엇을 만들고 있는가

많은 AI 비서가 최신 정보를 제공하거나 웹을 검색할 수 있는 기능을 갖추고 있지 않습니다. 이 MCP 서버는 두 가지 도구를 제공하여 이 문제를 해결합니다.

google_web_search : 웹에서 최신 정보를 검색합니다.
google_image_search : 검색어와 관련된 이미지 찾기

MCP 호환 클라이언트(예: Claude in Cursor, VSCode 또는 Claude Desktop)에 연결되면 AI 비서가 검색을 수행하고 최신 정보에 액세스할 수 있습니다.

핵심 MCP 개념

MCP 서버는 AI 어시스턴트에 기능을 제공합니다. 이 서버는 다음을 구현합니다.

도구 : AI가 호출할 수 있는 기능(사용자 승인 필요)
구조화된 커뮤니케이션 : MCP 프로토콜을 통한 표준화된 메시징 형식
전송 계층 : 표준 입출력을 통한 통신

필수 조건

Node.js(v18 이상) 및 npm
Google Cloud Platform 계정
Google 맞춤 검색 API 키 및 검색 엔진 ID
MCP 호환 클라이언트(데스크톱용 Claude, Cursor, Claude가 포함된 VSCode 등)

빠른 시작(이 저장소 복제)

서버를 처음부터 구축하지 않고 사용하려면 다음 단계를 따르세요.

지엑스피1

빌드 후 MCP 클라이언트에 연결 섹션에 따라 서버를 원하는 클라이언트에 연결하세요.

환경 설정(처음부터 구축)

서버를 처음부터 직접 구축하고 싶다면 다음 지침을 따르세요.

프로젝트 구조 생성

맥OS/리눅스

# Create a new directory for our project
mkdir google-search-mcp
cd google-search-mcp

# Initialize a new npm project
npm init -y

# Install dependencies
npm install @modelcontextprotocol/sdk dotenv zod
npm install -D @types/node typescript

# Create our files
mkdir src
touch src/index.ts

윈도우

# Create a new directory for our project
md google-search-mcp
cd google-search-mcp

# Initialize a new npm project
npm init -y

# Install dependencies
npm install @modelcontextprotocol/sdk dotenv zod
npm install -D @types/node typescript

# Create our files
md src
new-item src\index.ts

TypeScript 구성

루트 디렉토리에 tsconfig.json 만듭니다.

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "Node16",
    "moduleResolution": "Node16",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}

package.json 업데이트

package.json 에 다음이 포함되어 있는지 확인하세요.

{
  "name": "google_search_mcp",
  "version": "0.1.0",
  "description": "MCP server for Google Custom Search API integration",
  "license": "MIT",
  "type": "module",
  "bin": {
    "google_search": "./dist/index.js"
  },
  "files": [
    "dist"
  ],
  "scripts": {
    "build": "tsc",
    "build:unix": "tsc && chmod 755 dist/index.js",
    "prepare": "npm run build",
    "watch": "tsc --watch",
    "start": "node dist/index.js"
  }
}

Google API 설정

Google Cloud Platform을 설정하고 API 자격 증명을 받아야 합니다.

Google Cloud Platform 설정

Google Cloud Console 로 이동
새 프로젝트를 만듭니다
사용자 정의 검색 API 활성화:
Navigate to "APIs & Services" → "Library" Search for "Custom Search API" Click on "Custom Search API" → "Enable"
API 자격 증명을 만듭니다.
Navigate to "APIs & Services" → "Credentials" Click "Create Credentials" → "API key" Copy your API key

사용자 정의 검색 엔진 설정

프로그래밍 가능한 검색 엔진 으로 이동
새로운 검색 엔진을 만들려면 "추가"를 클릭하세요.
"전체 웹 검색"을 선택하고 검색 엔진의 이름을 지정하세요.
제어판에서 검색 엔진 ID(cx 값)를 가져옵니다.

환경 구성

루트 디렉토리에 .env 파일을 만듭니다.

GOOGLE_API_KEY=your_api_key_here
GOOGLE_CSE_ID=your_search_engine_id_here

자격 증명을 보호하려면 .gitignore 파일에 .env 추가하세요.

echo ".env" >> .gitignore

서버 구축

서버 구현 만들기

src/index.ts 에 서버 구현을 만듭니다.

import dotenv from "dotenv"
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import {
  CallToolRequestSchema,
  ListToolsRequestSchema,
  Tool,
} from "@modelcontextprotocol/sdk/types.js";

dotenv.config();

// Define your tools
const WEB_SEARCH_TOOL: Tool = {
  name: "google_web_search",
  description: "Performs a web search using Google's Custom Search API...",
  inputSchema: {
    // Schema details here
  },
};

const IMAGE_SEARCH_TOOL: Tool = {
  name: "google_image_search",
  description: "Searches for images using Google's Custom Search API...",
  inputSchema: {
    // Schema details here
  }
};

// Server implementation
const server = new Server(
  {
    name: "google-search",
    version: "0.1.0",
  },
  {
    capabilities: {
      tools: {},
    },
  },
);

// Check for API key and Search Engine ID
const GOOGLE_API_KEY = process.env.GOOGLE_API_KEY!;
const GOOGLE_CSE_ID = process.env.GOOGLE_CSE_ID!;

if (!GOOGLE_API_KEY || !GOOGLE_CSE_ID) {
  console.error("Error: Missing environment variables");
  process.exit(1);
}

// Tool handlers
server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [WEB_SEARCH_TOOL, IMAGE_SEARCH_TOOL],
}));

server.setRequestHandler(CallToolRequestSchema, async (request) => {
  // Implement tool handlers
});

// Run the server
async function runServer() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error("Google Search MCP Server running on stdio");
}

runServer().catch((error) => {
  console.error("Fatal error running server:", error);
  process.exit(1);
});

전체 구현 세부 사항은 저장소 파일을 참조하세요.

서버 구축

구현을 완료한 후 서버를 빌드합니다.

npm run build

이렇게 하면 TypeScript 코드가 dist 디렉토리의 JavaScript로 컴파일됩니다.

MCP 클라이언트에 연결

MCP 서버는 다양한 클라이언트에 연결할 수 있습니다. 자주 사용되는 클라이언트에 대한 설정 지침은 다음과 같습니다.

데스크톱용 클로드

맥OS/리눅스

구성 파일을 엽니다.

code ~/Library/Application\ Support/Claude/claude_desktop_config.json

서버 구성을 추가합니다.

{
  "mcpServers": {
    "google_search": {
      "command": "node",
      "args": [
        "/absolute/path/to/google-search-mcp/dist/index.js"
      ],
      "env": {
        "GOOGLE_API_KEY": "your_api_key_here",
        "GOOGLE_CSE_ID": "your_search_engine_id_here"
      }
    }
  }
}

윈도우

구성 파일을 엽니다.

code $env:AppData\Claude\claude_desktop_config.json

서버 구성을 추가합니다.

{
  "mcpServers": {
    "google_search": {
      "command": "node",
      "args": [
        "C:\\absolute\\path\\to\\google-search-mcp\\dist\\index.js"
      ],
      "env": {
        "GOOGLE_API_KEY": "your_api_key_here",
        "GOOGLE_CSE_ID": "your_search_engine_id_here"
      }
    }
  }
}

데스크톱용 Claude를 다시 시작하세요
인터페이스에서 도구 아이콘을 클릭하여 도구가 나타나는지 확인하세요.

클로드와 함께하는 VSCode

macOS/Linux 및 Windows

VSCode용 MCP 확장 프로그램 설치
작업 공간에서 .vscode/settings.json 만들거나 편집하세요.

macOS/Linux의 경우:

{
  "mcp.servers": {
    "google_search": {
      "command": "node",
      "args": [
        "/absolute/path/to/google-search-mcp/dist/index.js"
      ],
      "env": {
        "GOOGLE_API_KEY": "your_api_key_here",
        "GOOGLE_CSE_ID": "your_search_engine_id_here"
      }
    }
  }
}

Windows의 경우:

{
  "mcp.servers": {
    "google_search": {
      "command": "node",
      "args": [
        "C:\\absolute\\path\\to\\google-search-mcp\\dist\\index.js"
      ],
      "env": {
        "GOOGLE_API_KEY": "your_api_key_here",
        "GOOGLE_CSE_ID": "your_search_engine_id_here"
      }
    }
  }
}

VSCode를 다시 시작하세요
이 도구는 VSCode에서 Claude에게 제공됩니다.

커서

커서 설정 열기(기어 아이콘)
"MCP"를 검색하고 MCP 설정을 엽니다.
"새 MCP 서버 추가"를 클릭하세요.
위와 유사한 설정으로 구성하세요.

macOS/Linux의 경우:

{
  "mcpServers": {
    "google_search": {
      "command": "node",
      "args": [
        "/absolute/path/to/google-search-mcp/dist/index.js"
      ],
      "env": {
        "GOOGLE_API_KEY": "your_api_key_here",
        "GOOGLE_CSE_ID": "your_search_engine_id_here"
      }
    }
  }
}

Windows의 경우:

{
  "mcpServers": {
    "google_search": {
      "command": "node",
      "args": [
        "C:\\absolute\\path\\to\\google-search-mcp\\dist\\index.js"
      ],
      "env": {
        "GOOGLE_API_KEY": "your_api_key_here",
        "GOOGLE_CSE_ID": "your_search_engine_id_here"
      }
    }
  }
}

커서 재시작

서버 테스트

Claude와 함께 사용

연결되면 Claude에게 다음과 같은 질문을 하여 도구를 테스트할 수 있습니다.

"재생에너지에 대한 최신 뉴스를 검색하세요"
"전기 자동차 이미지 찾기"
"일본의 인기 관광지는 어디인가요?"

클로드는 필요할 때 자동으로 적절한 검색 도구를 사용합니다.

수동 테스트

서버를 직접 테스트할 수도 있습니다.

# Test web search
echo '{
  "jsonrpc": "2.0",
  "method": "callTool",
  "params": {
    "name": "google_web_search",
    "arguments": {
      "query": "test query",
      "count": 2
    }
  },
  "id": 1
}' | node dist/index.js

후드 아래에서 무슨 일이 일어나고 있나요?

질문을 할 때:

클라이언트가 귀하의 질문을 Claude에게 보냅니다.
Claude는 사용 가능한 도구를 분석하고 어떤 도구를 사용할지 결정합니다.
클라이언트는 MCP 서버를 통해 선택한 도구를 실행합니다.
결과는 Claude에게 다시 전송됩니다.
Claude는 검색 결과를 기반으로 자연어 응답을 공식화합니다.
응답이 표시됩니다

문제 해결

일반적인 문제

환경 변수

Error: GOOGLE_API_KEY environment variable is required .

# Check your .env file
cat .env

# Try setting environment variables directly:
export GOOGLE_API_KEY=your_key_here
export GOOGLE_CSE_ID=your_id_here

API 오류

API 오류가 발생하는 경우:

# Test your API credentials directly
curl "https://www.googleapis.com/customsearch/v1?key=YOUR_API_KEY&cx=YOUR_CX_ID&q=test"

연결 문제

클라이언트가 서버에 연결할 수 없는 경우:

# Verify the server runs correctly on its own
node dist/index.js

# Check file permissions
chmod 755 dist/index.js

# Ensure you're using absolute paths in your configuration

API 참조

`google_web_search`

Google의 맞춤 검색 API를 사용하여 웹 검색을 수행합니다.

매개변수:

query (문자열, 필수): 검색 쿼리
count (숫자, 선택 사항): 결과 수(1-10, 기본값 5)
start (숫자, 선택 사항): 페이지 시작 인덱스(기본값 1)
site (문자열, 선택 사항): 검색을 특정 사이트로 제한합니다(예: 'example.com')

`google_image_search`

Google의 맞춤 검색 API를 사용하여 이미지를 검색합니다.

매개변수:

query (문자열, 필수): 이미지 검색 쿼리
count (숫자, 선택 사항): 결과 수(1-10, 기본값 5)
start (숫자, 선택 사항): 페이지 시작 인덱스(기본값 1)

제한 사항

Google 맞춤 검색 API 무료 계층: 하루 100개 쿼리
서버에서 적용하는 속도 제한: 초당 5개 요청
쿼리당 최대 10개 결과(Google API 제한)

특허

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여되었습니다. 자세한 내용은 라이선스 파일을 참조하세요.

Google 검색 MCP 서버

우리가 무엇을 만들고 있는가

핵심 MCP 개념

필수 조건

빠른 시작(이 저장소 복제)

환경 설정(처음부터 구축)

프로젝트 구조 생성

맥OS/리눅스

윈도우

TypeScript 구성

package.json 업데이트

Google API 설정

Google Cloud Platform 설정

사용자 정의 검색 엔진 설정

환경 구성

서버 구축

서버 구현 만들기

서버 구축

MCP 클라이언트에 연결

데스크톱용 클로드

맥OS/리눅스

윈도우

클로드와 함께하는 VSCode

macOS/Linux 및 Windows

커서

서버 테스트

Claude와 함께 사용

수동 테스트

후드 아래에서 무슨 일이 일어나고 있나요?

문제 해결

일반적인 문제

환경 변수

API 오류

연결 문제

API 참조

google_web_search

google_image_search

제한 사항

특허

Appeared in Searches

`google_web_search`

`google_image_search`