@softsurgetech/gcloud-mcp-proxy
v1.0.0
Published
Stdio-to-HTTP MCP proxy for Google Cloud remote MCP servers (Firestore, Cloud Run, Discovery Engine, BigQuery, and more)
Maintainers
Readme
gcloud-mcp-proxy
Stdio-to-HTTP proxy for Google Cloud's remote MCP servers. One binary, any Google Cloud MCP endpoint.
Bridges MCP clients (JSON-RPC over stdin/stdout) to Google's managed MCP servers with automatic authentication via ADC, service account, or API key.
Supported Services
| Service | MCP_ENDPOINT |
|---------|-------------|
| Agent Search | https://discoveryengine.googleapis.com/mcp |
| Firestore | https://firestore.googleapis.com/mcp |
| Cloud Run | https://run.googleapis.com/mcp |
| Cloud SQL | https://sqladmin.googleapis.com/mcp |
| Cloud Storage | https://storage.googleapis.com/storage/mcp |
| BigQuery | https://bigquery.googleapis.com/mcp |
| Pub/Sub | https://pubsub.googleapis.com/mcp |
| Cloud Logging | https://logging.googleapis.com/mcp |
| Cloud Monitoring | https://monitoring.googleapis.com/mcp |
| Vertex AI | https://aiplatform.googleapis.com/mcp |
| GKE | https://container.googleapis.com/mcp |
| Compute Engine | https://compute.googleapis.com/mcp |
| Spanner | https://spanner.googleapis.com/mcp |
Full list: https://docs.cloud.google.com/mcp/supported-products
Quick Start
make setup # Install deps + pre-commit hook
make validate # Compile + test all endpointsAuthentication
Three methods, checked in priority order:
| Priority | Method | Env Variable | Use Case |
|----------|--------|-------------|----------|
| 1 | API Key | GOOGLE_API_KEY | Simple, no OAuth — limited access |
| 2 | Service Account | GOOGLE_SERVICE_ACCOUNT_KEY_FILE | Path to SA JSON — CI/CD, servers |
| 3 | ADC | (automatic) | gcloud auth application-default login — local dev |
Error Messages
If auth is misconfigured:
[gcloud-mcp-proxy] ERROR: Authentication failed.
Could not load the default credentials.
To fix, do one of:
1. Run: gcloud auth application-default login
2. Set GOOGLE_SERVICE_ACCOUNT_KEY_FILE=/path/to/sa-key.json
3. Set GOOGLE_API_KEY=your-api-keyIf MCP_ENDPOINT is missing:
[gcloud-mcp-proxy] ERROR: MCP_ENDPOINT is required.
Set MCP_ENDPOINT to a Google Cloud MCP server URL:
Agent Search: https://discoveryengine.googleapis.com/mcp
Firestore: https://firestore.googleapis.com/mcp
...Make Targets
| Target | What it does |
|--------|-------------|
| make setup | Install deps + git pre-commit hook |
| make compile | TypeScript → dist/ |
| make lint | ESLint |
| make scan | Lint + gitleaks + semgrep |
| make build | compile + scan |
| make validate | Compile + test all service endpoints |
| make package | build + verify output |
| make release | package + git tag + push |
| make publish | package + npm publish |
| make start | Compile + run proxy (requires MCP_ENDPOINT) |
| make stop | Kill backgrounded proxy |
| make restart | stop + start |
| make clean | Remove dist/ + node_modules/ |
Output
$ make scan
✓ Lint — No Issues Found
✓ Secrets — No Secrets Detected
✓ SAST — No Issues Found
$ make validate
✓ Agent Search — Connected
✓ Firestore — Connected
✓ Cloud Run — Connected
✓ Cloud SQL — Connected
✓ Cloud Storage — Connected
✓ Pub/Sub — Connected
6 passed, 0 failedPre-commit Hook
Installed by make setup. Runs make scan on every commit:
- ESLint (TypeScript)
- gitleaks (secret detection)
- semgrep (SAST)
MCP Client Configuration
Set MCP_ENDPOINT to choose which Google Cloud service to proxy. Run one instance per service.
Firestore
{
"mcpServers": {
"gcp-firestore": {
"command": "node",
"args": ["/path/to/gcloud-mcp-proxy/dist/index.js"],
"env": {
"MCP_ENDPOINT": "https://firestore.googleapis.com/mcp"
}
}
}
}Agent Search (Discovery Engine)
{
"mcpServers": {
"gcp-agent-search": {
"command": "node",
"args": ["/path/to/gcloud-mcp-proxy/dist/index.js"],
"env": {
"MCP_ENDPOINT": "https://discoveryengine.googleapis.com/mcp"
}
}
}
}Cloud Run
{
"mcpServers": {
"gcp-cloud-run": {
"command": "node",
"args": ["/path/to/gcloud-mcp-proxy/dist/index.js"],
"env": {
"MCP_ENDPOINT": "https://run.googleapis.com/mcp"
}
}
}
}Multiple services (one proxy per service)
{
"mcpServers": {
"gcp-firestore": {
"command": "node",
"args": ["/path/to/gcloud-mcp-proxy/dist/index.js"],
"env": { "MCP_ENDPOINT": "https://firestore.googleapis.com/mcp" }
},
"gcp-cloud-run": {
"command": "node",
"args": ["/path/to/gcloud-mcp-proxy/dist/index.js"],
"env": { "MCP_ENDPOINT": "https://run.googleapis.com/mcp" }
},
"gcp-agent-search": {
"command": "node",
"args": ["/path/to/gcloud-mcp-proxy/dist/index.js"],
"env": { "MCP_ENDPOINT": "https://discoveryengine.googleapis.com/mcp" }
}
}
}With Service Account (for CI/CD)
{
"mcpServers": {
"gcp-firestore": {
"command": "node",
"args": ["/path/to/gcloud-mcp-proxy/dist/index.js"],
"env": {
"MCP_ENDPOINT": "https://firestore.googleapis.com/mcp",
"GOOGLE_SERVICE_ACCOUNT_KEY_FILE": "/path/to/sa-key.json"
}
}
}
}How It Works
- MCP client sends JSON-RPC messages to proxy's stdin (one per line)
- Proxy reads
MCP_ENDPOINTenv var to determine target - Authenticates with Google Cloud (ADC / API key / SA)
- POSTs the JSON-RPC message to the endpoint with Bearer token
- Writes response to stdout
- Errors and diagnostics go to stderr (won't pollute JSON-RPC)
Prerequisites
- Node.js 20+
- pnpm
- Authentication (one of):
gcloud auth application-default loginGOOGLE_API_KEYenv varGOOGLE_SERVICE_ACCOUNT_KEY_FILEenv var
- The target GCP API must be enabled in your project
- For scans:
gitleaks,semgrep
Publishing
Option A: Public npm registry (npmjs.com)
npm login # One-time: authenticate to npmjs.com
make publish # Builds, scans, publishesConsumers install with:
npx gcloud-mcp-proxy # Run directly
# or
npm install -g gcloud-mcp-proxyOption B: GitLab npm registry (gitlab.com)
- Scope the package in
package.json:
{ "name": "@softsurgetech/gcloud-mcp-proxy" }- Add
.npmrcto the repo:
@softsurgetech:registry=https://gitlab.com/api/v4/projects/PROJECT_ID/packages/npm/
//gitlab.com/api/v4/projects/PROJECT_ID/packages/npm/:_authToken=${GITLAB_TOKEN}- Publish:
npm publishConsumers need registry config to install:
npm install @softsurgetech/gcloud-mcp-proxy --registry=https://gitlab.com/api/v4/projects/PROJECT_ID/packages/npm/Recommendation
Use npmjs.com for public distribution — zero config for consumers. Use GitLab registry if you want to keep it within your org or need GitLab CI job token auth for publishing.
Development
make setup # Install everything
make build # Compile + full scan
make validate # Test all endpointsRepository
gitlab.com/softsurgetech/ai/mcp/vertex-ai-mcp-proxy
License
MIT
