如何在 Claude Code 中使用 Gemini MCP Server (2026)

如何在 Claude Code (2026) 中使用 Gemini MCP Server

Claude Code 是 Anthropic 官方推出的 AI 辅助开发 CLI 工具。它本身功能强大，但通过 Model Context Protocol (MCP)，你可以为其扩展外部工具和数据源——包括 Google 的 Gemini 模型。

通过将 Gemini MCP server 连接到 Claude Code，你可以结合 Gemini 的优势（超长上下文窗口、免费 API 访问、多模态能力）与 Claude 的编程能力。本指南将逐步向你展示如何进行配置。

什么是 MCP？

Model Context Protocol (MCP) 是由 Anthropic 创建的开放标准，旨在让 AI 助手连接到外部工具和数据源。你可以把它想象成 AI 的 USB 接口——任何兼容 MCP 的工具都可以插入任何兼容 MCP 的客户端。

核心概念：

• MCP Server —— 暴露工具和资源的程序（例如 Gemini API 的封装器）。
• MCP Client —— 使用这些工具的 AI 助手（例如 Claude Code）。
• Tools（工具） —— AI 可以调用的函数（如“使用 Gemini 生成文本”）。
• Resources（资源） —— AI 可以读取的数据（如文件、数据库或 API 响应）。

为什么要配合 Claude Code 使用 Gemini？

将 Gemini 引入你的 Claude Code 工作流有许多实际理由：

优势	详情
免费 API 访问	Gemini 每天提供超过 100 万个免费 token，可延长你的 Claude 使用额度
超长上下文	Gemini 2.5 Pro 可处理高达 100 万 token，适用于大型代码库
多模态能力	可向 Gemini 发送图片和截图进行分析
第二意见	针对关键决策对比 Claude 和 Gemini 的输出结果
成本优化	将简单任务分配给免费的 Gemini，复杂任务交给 Claude

准备工作

在开始之前，请确保你拥有：

1. 已安装 Claude Code —— 通过 npm install -g @anthropic-ai/claude-code 安装，或参考 官方文档。
2. Node.js 18+ —— 运行 MCP server 所需。
3. Google AI Studio API key —— 在 aistudio.google.com 免费获取。

方法 1：使用官方 Gemini MCP Server

Google 为 Gemini 提供了一个官方 MCP server。这是最简单的方法。

步骤 1：配置 Claude Code

打开你的 Claude Code MCP 配置文件。你可以在 Claude Code 中执行：

claude mcp add gemini

或者手动编辑配置文件 ~/.claude/claude_desktop_config.json（或项目级的 .mcp.json）：

{
  "mcpServers": {
    "gemini": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/gemini-mcp-server"],
      "env": {
        "GOOGLE_API_KEY": "AIza-your-free-key"
      }
    }
  }
}

步骤 2：验证连接

重启 Claude Code 并检查 Gemini 工具是否可用：

claude
# 然后输入: /mcp

你应该能看到列出的 Gemini server 及其可用工具。

步骤 3：在 Claude Code 中使用 Gemini 工具

连接后，你可以直接要求 Claude Code 使用 Gemini：

Use the Gemini tool to analyze this large codebase summary and identify architectural issues.

Claude Code 会在合适时自动将请求路由到 Gemini MCP server。

方法 2：构建自定义 Gemini MCP Server

为了获得更多控制权，你可以构建自己的 MCP server 来封装 Gemini API。这允许你添加针对个人工作流定制的工具。

步骤 1：初始化项目

mkdir gemini-mcp-server
cd gemini-mcp-server
npm init -y
npm install @modelcontextprotocol/sdk @google/generative-ai

步骤 2：创建 Server

创建 index.js：

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { GoogleGenerativeAI } from "@google/generative-ai";
import { z } from "zod";

const genAI = new GoogleGenerativeAI(process.env.GOOGLE_API_KEY);

const server = new McpServer({
  name: "gemini-mcp",
  version: "1.0.0",
});

// 工具：使用 Gemini 生成文本
server.tool(
  "gemini_generate",
  "Generate text using Google Gemini",
  {
    prompt: z.string().describe("The prompt to send to Gemini"),
    model: z.string().optional().describe("Model name (default: gemini-2.5-pro)"),
  },
  async ({ prompt, model }) => {
    const geminiModel = genAI.getGenerativeModel({
      model: model || "gemini-2.5-pro",
    });
    const result = await geminiModel.generateContent(prompt);
    return {
      content: [{ type: "text", text: result.response.text() }],
    };
  }
);

// 工具：使用 Gemini 分析图片
server.tool(
  "gemini_analyze_image",
  "Analyze an image using Gemini Vision",
  {
    imagePath: z.string().describe("Path to the image file"),
    question: z.string().describe("What to analyze about the image"),
  },
  async ({ imagePath, question }) => {
    const fs = await import("fs");
    const imageData = fs.readFileSync(imagePath);
    const base64Image = imageData.toString("base64");
    const mimeType = imagePath.endsWith(".png") ? "image/png" : "image/jpeg";

    const geminiModel = genAI.getGenerativeModel({ model: "gemini-2.5-pro" });
    const result = await geminiModel.generateContent([
      question,
      { inlineData: { data: base64Image, mimeType } },
    ]);

    return {
      content: [{ type: "text", text: result.response.text() }],
    };
  }
);

// 工具：利用 Gemini 的长上下文总结大文件
server.tool(
  "gemini_summarize_file",
  "Summarize a large file using Gemini's 1M token context window",
  {
    filePath: z.string().describe("Path to the file to summarize"),
    instruction: z.string().optional().describe("Specific summarization instruction"),
  },
  async ({ filePath, instruction }) => {
    const fs = await import("fs");
    const content = fs.readFileSync(filePath, "utf-8");

    const geminiModel = genAI.getGenerativeModel({ model: "gemini-2.5-pro" });
    const prompt = instruction
      ? `${instruction}\n\nFile content:\n${content}`
      : `Summarize this file, highlighting key components, functions, and architecture:\n\n${content}`;

    const result = await geminiModel.generateContent(prompt);
    return {
      content: [{ type: "text", text: result.response.text() }],
    };
  }
);

// 启动 server
const transport = new StdioServerTransport();
await server.connect(transport);

更新 package.json：

{
  "type": "module",
  "main": "index.js",
  "bin": {
    "gemini-mcp": "./index.js"
  }
}

步骤 3：在 Claude Code 中注册

将你的自定义 server 添加到 Claude Code 的 MCP 配置中：

{
  "mcpServers": {
    "gemini": {
      "command": "node",
      "args": ["/path/to/gemini-mcp-server/index.js"],
      "env": {
        "GOOGLE_API_KEY": "AIza-your-free-key"
      }
    }
  }
}

步骤 4：测试集成

启动 Claude Code 并尝试以下命令：

Use the gemini_generate tool to explain the Observer pattern with a TypeScript example.

Use the gemini_summarize_file tool to summarize ./src/index.ts

Use the gemini_analyze_image tool to describe the UI in ./screenshot.png

实际应用案例

1. 双模型代码审查

让 Claude Code 审查你的代码，然后用 Gemini 进行交叉验证：

Review the file ./src/auth.ts for security issues.
Then use the gemini_generate tool to also review the same code and compare the findings.

2. 大型代码库分析

Gemini 的 100 万 token 上下文窗口可以处理超出 Claude 上下文限制的整个代码库：

Use the gemini_summarize_file tool to analyze the concatenated output
of all files in ./src/ and identify the overall architecture.

3. 截图转代码

利用 Gemini 对 UI 截图的视觉能力：

Use the gemini_analyze_image tool to describe the layout in ./mockup.png,
then write the React component to match it.

故障排除

问题	解决方案
/mcp 中未显示 Server	重启 Claude Code。检查 JSON 配置文件的语法。
"API key not valid"	在 aistudio.google.com 验证你的 key。确保环境变量设置正确。
超时错误	Gemini 免费层在高峰时段可能较慢。请添加重试逻辑。
"Model not found"	检查模型名称。使用 gemini-2.5-pro 或 gemini-2.0-flash。
权限被拒绝	确保 Node.js 拥有访问你引用的文件路径的权限。

高效使用技巧

1. 按复杂度路由。 简单任务使用 Gemini Flash（免费且快速），复杂推理使用 Claude。
2. 使用结构化输出。 要求 Gemini 返回 JSON，以便在你的 MCP 工具中更容易解析。
3. 缓存结果。 存储 Gemini 的响应以避免重复的 API 调用。
4. 组合工具。 将 Gemini 的分析与 Claude 的代码生成连接起来，以获得最佳效果。

总结

通过 MCP 将 Gemini 连接到 Claude Code，你可以兼得两个模型的优势：Claude 卓越的编程能力，以及 Gemini 的免费 API 访问、超长上下文窗口和多模态能力。只需不到 10 分钟即可完成设置，工作流的提升立竿见影。

如果你正在构建需要多媒体生成（图像、视频、数字人或语音）的 AI 应用，免费试用 Hypereal AI —— 35 个积分，无需信用卡。它提供了对 50 多种媒体模型的 API 访问，能完美适配任何开发环境。