Google 搜索 MCP 服务器

一个模型上下文协议 (MCP) 服务器，通过 Google 的自定义搜索 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 云端平台帐户
Google 自定义搜索 API 密钥和搜索引擎 ID
与 MCP 兼容的客户端（Claude for Desktop、Cursor、VSCode with Claude 等）

快速启动（克隆此存储库）

如果您不想从头开始构建此服务器，请按照以下步骤操作：

# 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

视窗

# 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 云平台设置

前往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

将.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

这会将dist目录中的 TypeScript 代码编译为 JavaScript。

连接到 MCP 客户端

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

克劳德桌面版

macOS/Linux

打开您的配置文件：

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 桌面版
通过单击界面中的工具图标来验证工具是否出现

与 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 询问以下问题来测试该工具：

“搜索有关可再生能源的最新消息”
“查找电动汽车的图像”
“日本最热门的旅游目的地有哪些？”

当需要时，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 根据搜索结果制定自然语言响应
响应将显示给您

故障排除

常见问题

环境变量

如果您看到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 许可证获得许可 - 有关详细信息，请参阅 LICENSE 文件。

Google 搜索 MCP 服务器

我们正在构建什么

核心 MCP 概念

先决条件

快速启动（克隆此存储库）

设置您的环境（从头开始构建）

创建项目结构

macOS/Linux

视窗

配置 TypeScript

更新 package.json

Google API 设置

Google 云平台设置

自定义搜索引擎设置

环境配置

构建您的服务器

创建服务器实现

构建服务器

连接到 MCP 客户端

克劳德桌面版

macOS/Linux

视窗

与 Claude 一起编写 VSCode

macOS/Linux 和 Windows

光标

测试您的服务器

与 Claude 一起使用

手动测试

幕后发生了什么

故障排除

常见问题

环境变量

API 错误

连接问题

API 参考

google_web_search

google_image_search

限制

执照

Appeared in Searches

`google_web_search`

`google_image_search`