Google Search MCP Server

Google Search MCP 服务

一个 Model Context Protocol（MCP）服务，通过 Google 的 Custom Search API 提供网页和图片搜索功能。此服务遵循 MCP 规范，可与 Claude 及其他 AI 助手集成。

我们要构建什么

许多 AI 助手缺少最新信息，也无法搜索网页。此 MCP 服务提供两种工具来解决这一问题：

• google_web_search：搜索网页以获取最新信息
• google_image_search：查找与查询相关的图片

连接到兼容 MCP 的客户端（例如 Cursor、VSCode 或 Claude Desktop 中的 Claude）后，你的 AI 助手便可执行搜索并获取最新信息。

MCP 核心概念

MCP 服务为 AI 助手提供功能。此服务实现了：

• 工具：可由 AI 调用的函数（需获得用户批准）
• 结构化通信：通过 MCP 协议使用标准化的消息格式
• 传输层：通过标准输入／输出进行通信

前提条件

• Node.js（v18 或更高版本）和 npm
• Google Cloud Platform 账号
• Google Custom Search API 密钥和 Search Engine ID
• 兼容 MCP 的客户端（Claude for Desktop、Cursor、配备 Claude 的 VSCode 等）

快速开始（克隆此仓库）

如果你想直接使用此服务，而不从头构建，请按以下步骤操作：

# Clone the repository
git clone https://github.com/yourusername/google-search-mcp-server.git
cd google-search-mcp-server

# Install dependencies
npm install

# Set up your environment variables
# Setup .env file in the root folder of the project

# On macOS/Linux
touch .env

# On Windows
new-item .env

# Edit .env file to add your Google API credentials
# Use any text editor you prefer (VS Code, Notepad, nano, vim, etc.)
# Add these to your newly created .env

GOOGLE_API_KEY=your_api_key_here
GOOGLE_CSE_ID=your_search_engine_id_here

# Build the server
npm run build

# Test the server (optional)
# On macOS/Linux
echo '{"jsonrpc":"2.0","method":"listTools","id":1}' | node dist/index.js

# On Windows PowerShell
echo '{"jsonrpc":"2.0","method":"listTools","id":1}' | node dist/index.js

# On Windows CMD
echo {"jsonrpc":"2.0","method":"listTools","id":1} | node dist/index.js

构建完成后，请按照连接到 MCP 客户端部分的说明，将服务连接到你首选的客户端。

设置环境（从头构建）

如果你希望从头开始自行构建此服务，请按照以下说明操作：

创建项目结构

macOS/Linux

# 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

Windows

# 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 设置

1. 前往 Google Cloud Console
2. 创建一个新项目
3. 启用 Custom Search API：

   Navigate to "APIs & Services" → "Library"
   Search for "Custom Search API"
   Click on "Custom Search API" → "Enable"
   

4. 创建 API 凭据：

   Navigate to "APIs & Services" → "Credentials"
   Click "Create Credentials" → "API key"
   Copy your API key
   

Custom Search Engine 设置

1. 前往 Programmable Search Engine
2. 点击“Add”以创建新的搜索引擎
3. 选择“Search the entire web”并为搜索引擎命名
4. 从控制面板获取 Search Engine ID（cx 值）

环境配置

在根目录中创建一个 .env 文件：

GOOGLE_API_KEY=your_api_key_here
GOOGLE_CSE_ID=your_search_engine_id_here

将 .env 添加到 .gitignore 文件中，以保护你的凭据：

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 代码编译为 JavaScript，并输出到 dist 目录中。

连接到 MCP 客户端

MCP 服务可以连接到各种客户端。以下是一些常用客户端的设置说明：

Claude for Desktop

macOS/Linux

1. 打开配置文件：

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

2. 添加服务配置：

{
  "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

1. 打开配置文件：

code $env:AppData\Claude\claude_desktop_config.json

2. 添加服务配置：

{
  "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"
      }
    }
  }
}

3. 重启 Claude for Desktop
4. 点击界面中的工具图标，确认工具是否显示

配备 Claude 的 VSCode

macOS/Linux 和 Windows

1. 安装 VSCode 的 MCP 扩展
2. 在工作区中创建或编辑 .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"
      }
    }
  }
}

3. 重启 VSCode
4. Claude 在 VSCode 中即可使用这些工具

Cursor

1. 打开 Cursor 设置（齿轮图标）
2. 搜索“MCP”并打开 MCP 设置
3. 点击“Add new MCP server”
4. 使用与上述类似的设置进行配置：

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"
      }
    }
  }
}

5. 重启 Cursor

测试你的服务

与 Claude 配合使用

连接后，你可以向 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

底层运行机制

当你提出问题时：

1. 客户端将你的问题发送给 Claude
2. Claude 分析可用的工具，并决定使用哪个工具
3. 客户端通过你的 MCP 服务执行所选工具
4. 结果会发送回 Claude
5. Claude 根据搜索结果生成自然语言回复
6. 回复会显示给你

故障排除

常见问题

环境变量

如果你看到 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 Custom Search API 执行网页搜索。

参数：

• query（字符串，必填）：搜索查询
• count（数字，可选）：结果数量（1-10，默认值为 5）
• start（数字，可选）：分页起始索引（默认值为 1）
• site（字符串，可选）：将搜索范围限制在特定网站（例如，'example.com'）

google_image_search

使用 Google Custom Search API 搜索图片。

参数：

• query（字符串，必填）：图片搜索查询
• count（数字，可选）：结果数量（1-10，默认值为 5）
• start（数字，可选）：分页起始索引（默认值为 1）

限制

• Google Custom Search API 免费套餐：每天 100 次查询
• 服务端强制速率限制：每秒 5 次请求
• 每次查询最多返回 10 条结果（Google API 限制）

许可证

本项目采用 MIT License 许可，详情请参阅 LICENSE 文件。