Google Search MCP 服务器

一个通过 Google 的自定义搜索 API 提供网页和图片搜索功能的模型上下文协议 (MCP) 服务器。此服务器遵循 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 自定义搜索 API 密钥和搜索引擎 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. 启用自定义搜索 API：

   导航到 "APIs & Services" → "Library"
   搜索 "Custom Search API"
   点击 "Custom Search API" → "Enable"
   

4. 创建 API 凭证：

   导航到 "APIs & Services" → "Credentials"
   点击 "Create Credentials" → "API key"
   复制您的 API 密钥
   

自定义搜索引擎设置

1. 前往 可编程搜索引擎
2. 点击 "Add" 创建一个新的搜索引擎
3. 选择 "Search the entire web" 并命名您的搜索引擎
4. 从控制面板获取您的搜索引擎 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

1. 添加服务器配置：

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

1. 添加服务器配置：

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

1. 重启 Claude for Desktop
2. 通过点击界面中的工具图标来验证工具是否出现

VSCode with Claude

macOS/Linux & Windows

1. 安装 MCP Extension for VSCode
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"
      }
    }
  }
}

1. 重启 VSCode
2. 工具将在 VSCode 中对 Claude 可用

Cursor

1. 打开 Cursor 设置（齿轮图标）
2. 搜索 "MCP" 并打开 MCP 设置
3. 点击 "添加新的 MCP 服务器"
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"
      }
    }
  }
}

1. 重启 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 的自定义搜索 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 文件。