Vertex MCP Server

顶点AI MCP服务器

模型上下文协议（MCP）服务器，将Google Cloud Vertex AI Gemini模型暴露给Claude Code、GitHub Copilot和其他MCP兼容工具等AI助手。

特性

• 🤖 三个强大的工具:

- gemini_query：通用人工智能查询 - gemini_query_with_search：基于网络搜索的实时响应 - gemini_code_review：AI驱动的代码审查，并提供详细的反馈

• 🚀 生产就绪:

- HTTP传输，便于集成 - 优雅的停机处理 - 全面的错误处理 - 符合JSON-RPC 2.0标准

• 🔒 安全:

- 使用Google Cloud服务帐户身份验证 - 没有硬编码凭据 - 基于环境的配置

先决条件

1. 转到1.24+ （已安装✓)
2. 谷歌云项目 与：

- Vertex AI API已启用 - 服务帐户 roles/aiplatform.user 许可 - 服务帐户密钥JSON文件

快速开始

1.设置Google Cloud凭据

如果您尚未设置Vertex AI，请按照以下步骤操作：

# Set your project
export GCP_PROJECT_ID=ai-orchestrator-482302

# Enable Vertex AI API
gcloud services enable aiplatform.googleapis.com

# Create service account (if not exists)
gcloud iam service-accounts create gemini-api-access \
    --display-name="Gemini API Access"

# Grant permissions
gcloud projects add-iam-policy-binding $GCP_PROJECT_ID \
    --member="serviceAccount:gemini-api-access@${GCP_PROJECT_ID}.iam.gserviceaccount.com" \
    --role="roles/aiplatform.user"

# Create key
mkdir -p ~/.ai_orchestrator
gcloud iam service-accounts keys create ~/.ai_orchestrator/vertex-ai-key.json \
    --iam-account=gemini-api-access@${GCP_PROJECT_ID}.iam.gserviceaccount.com

chmod 600 ~/.ai_orchestrator/vertex-ai-key.json

2.配置环境

# Copy example env file
cp .env.example .env

# Edit .env with your values
# Update GOOGLE_APPLICATION_CREDENTIALS with your actual username

3.构建和运行

# Build the server
go build -o bin/gemini-mcp ./cmd/server

# Run the server (env loaded automatically from .env)
./bin/gemini-mcp

# Or install to PATH for global access
go build -o ~/.local/bin/gemini-mcp ./cmd/server
gemini-mcp

您应该看到：

Starting Vertex AI MCP Server...
Configuration:
  Project ID: ai-orchestrator-482302
  Location: global
  Model: gemini-3-pro-preview
  Port: 8080
✓ Vertex AI client initialized
✓ MCP server created
🚀 Server listening on http://localhost:8080

测试服务器

卷曲测试

# Test initialization
curl -X POST http://localhost:8080 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-06-18"
    }
  }'

# List available tools
curl -X POST http://localhost:8080 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list",
    "params": {}
  }'

# Call gemini_query tool
curl -X POST http://localhost:8080 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "gemini_query",
      "arguments": {
        "prompt": "Explain quantum computing in simple terms"
      }
    }
  }'

# Call code review tool
curl -X POST http://localhost:8080 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "tools/call",
    "params": {
      "name": "gemini_code_review",
      "arguments": {
        "code": "def factorial(n):\n    if n == 0: return 1\n    return n * factorial(n-1)",
        "language": "python"
      }
    }
  }'

与AI工具集成

克劳德代码（VS代码扩展）

添加到您的VS代码设置(.vscode/settings.json 或全局设置）：

{
  "claude.mcpServers": {
    "vertex-gemini": {
      "type": "http",
      "url": "http://localhost:8080",
      "enabled": true
    }
  }
}

或者使用Claude Code CLI配置(~/.claude/config.json):

{
  "mcpServers": {
    "vertex-gemini": {
      "command": "/path/to/vertex-mcp-server/bin/vertex-mcp-server"
    }
  }
}

GitHub Copilot（通过MCP桥）

GitHub Copilot尚未原生支持MCP，但您可以通过桥接协议的工具使用它。请参阅下面的“GitHub Copilot集成”部分。

Cline（VS代码扩展）

添加到Cline的MCP设置(.cline/settings.json):

{
  "mcpServers": {
    "vertex-gemini": {
      "httpUrl": "http://localhost:8080"
    }
  }
}

可用工具

1.gemini_query

向Gemini查询一般任务、编码帮助、解释等。

参数：

• prompt （必填）：问题或提示

例子：

{
  "name": "gemini_query",
  "arguments": {
    "prompt": "Write a Python function to reverse a string"
  }
}

2.gemini_query_with_search

以实时网络搜索为基础查询Gemini。最适合当前事件、最新数据或可能已更改的信息。

参数：

• prompt （必填）：问题或提示

例子：

{
  "name": "gemini_query_with_search",
  "arguments": {
    "prompt": "What are the latest features in Go 1.25?"
  }
}

3.gemini_code_review

获得AI驱动的代码审查和详细的反馈。

参数：

• code （必填）：需审查的代码
• language （必填）：编程语言（例如“go”、“python”、“javascript”）
• focus （可选）：要关注的具体方面（例如，“安全性”、“性能”）

例子：

{
  "name": "gemini_code_review",
  "arguments": {
    "code": "func Add(a, b int) int { return a + b }",
    "language": "go",
    "focus": "best practices"
  }
}

配置

所有配置都是通过环境变量完成的：

模型选项

• gemini-3-pro-preview （默认）：最新推理模型（仅全局）
• gemini-3-flash-preview：快速推理模型（仅限全局）
• gemini-2.0-flash：生产就绪快速型号（稳定）
• gemini-1.5-pro：高级推理
• gemini-1.5-flash：成本效益高

发展

项目结构

vertex-mcp-server/
├── cmd/
│   └── server/
│       └── main.go           # Entry point
├── internal/
│   ├── mcp/
│   │   ├── server.go         # MCP server implementation
│   │   └── tools.go          # Tool definitions and handlers
│   └── vertexai/
│       └── client.go         # Vertex AI client wrapper
├── config/                   # Configuration files
├── .env.example             # Example environment file
├── README.md                # This file
└── go.mod                   # Go module definition

建筑

# Build for current platform
go build -o bin/vertex-mcp-server ./cmd/server

# Build for multiple platforms
GOOS=linux GOARCH=amd64 go build -o bin/vertex-mcp-server-linux ./cmd/server
GOOS=darwin GOARCH=arm64 go build -o bin/vertex-mcp-server-darwin ./cmd/server
GOOS=windows GOARCH=amd64 go build -o bin/vertex-mcp-server.exe ./cmd/server

在发展中奔跑

# Run directly with go run
source .env
go run ./cmd/server

部署

码头工人

FROM golang:1.25-alpine AS builder
WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN go build -o vertex-mcp-server ./cmd/server

FROM alpine:latest
RUN apk --no-cache add ca-certificates
WORKDIR /root/
COPY --from=builder /app/vertex-mcp-server .
ENV PORT=8080
EXPOSE 8080
CMD ["./vertex-mcp-server"]

云运行

# Build and deploy to Cloud Run
gcloud run deploy vertex-mcp-server \
  --source . \
  --region us-central1 \
  --set-env-vars GOOGLE_CLOUD_PROJECT=ai-orchestrator-482302 \
  --set-env-vars GOOGLE_CLOUD_LOCATION=us-central1 \
  --allow-unauthenticated

故障排除

“创建Vertex AI客户端失败”

解决方案： 检查您的凭据：

echo $GOOGLE_APPLICATION_CREDENTIALS
ls -l $GOOGLE_APPLICATION_CREDENTIALS

“拒绝许可”

解决方案： 确保您的服务帐户具有正确的角色：

gcloud projects get-iam-policy $GCP_PROJECT_ID \
  --flatten="bindings[].members" \
  --filter="bindings.members:serviceAccount:gemini-api-access*"

“找不到模型”

解决方案： 查看您所在地区的可用型号：

gcloud ai models list --region=us-central1 | grep gemini

测试时连接被拒绝

解决方案： 确保服务器正在运行：

# Check if server is running
lsof -i :8080

# Check logs
./bin/vertex-mcp-server

成本考虑

使用此MCP服务器会产生Google Cloud Vertex AI成本：

提示： 使用 gemini-1.5-flash 对于大多数任务，以最大限度地降低成本。

安全最佳实践

1. 从不提交凭据:

   echo ".env" >> .gitignore
   echo "*.json" >> .gitignore

1. 限制服务帐户权限:

- 仅授予 roles/aiplatform.user （不是 owner 或 editor)

1. 定期旋转按键:

   # List keys
   gcloud iam service-accounts keys list \
     --iam-account=gemini-api-access@${GCP_PROJECT_ID}.iam.gserviceaccount.com

   # Delete old keys
   gcloud iam service-accounts keys delete KEY_ID \
     --iam-account=gemini-api-access@${GCP_PROJECT_ID}.iam.gserviceaccount.com

1. 使用环境变量：切勿在源代码中硬编码凭据

1. 监控使用情况：在Google Cloud Console中设置账单提醒

GitHub复制集成

GitHub Copilot本身不支持MCP协议。但是，您可以：

选项1：分别使用这两种工具

• 使用GitHub Copilot获取内联代码建议
• 使用Claude Code（与此MCP服务器一起）进行复杂的查询和代码审查

选项2:MCP网桥（高级）

创建一个在GitHub Copilot的API和MCP协议之间转换的桥梁。这将需要定制中间件。

选项3:VS代码任务

创建通过curl调用MCP服务器的VS Code任务：

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Ask Gemini",
      "type": "shell",
      "command": "curl -X POST http://localhost:8080 -H 'Content-Type: application/json' -d '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/call\",\"params\":{\"name\":\"gemini_query\",\"arguments\":{\"prompt\":\"${input:prompt}\"}}}'",
      "problemMatcher": []
    }
  ],
  "inputs": [
    {
      "id": "prompt",
      "type": "promptString",
      "description": "What would you like to ask Gemini?"
    }
  ]
}

贡献

欢迎投稿！拜托：

1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 提交拉取请求

许可证

MIT许可证-有关详细信息，请参阅许可证文件

支持

对于问题：

1. 检查 故障排除 部分
2. 审查 顶点AI文档
3. 检查 MCP规范

致谢

• 建于 谷歌云顶点AI
• 用途 模型上下文协议
• 灵感源自 谷歌Codelabs MCP教程