Google Cloud Docs MCP Server

Instructions

Implementation Reference

• src/index.ts:658-891 (handler)

  Primary handler function implementing the search_google_cloud_docs tool. Performs Google search targeted at cloud.google.com, fallback to direct Cloud search, generates fallback paths from extensive topic mappings, scores relevance, fetches and extracts content from top 3 results.
  async function searchGoogleCloudDocs( query: string, product?: string ): Promise<string> { const results: { url: string; title?: string; snippet?: string; content?: string; error?: string; }[] = []; const queryLower = query.toLowerCase(); // Step 1: Try to search using Google let searchResults = await searchGoogleForCloudDocs(query, product); // Step 2: If no results, try direct Google Cloud search if (searchResults.length === 0) { searchResults = await searchCloudGoogleDirect(query); } // Step 3: Build fallback paths from topic mappings (always, to supplement Google results) const potentialPaths: string[] = []; // Check for product keywords for (const [key, value] of Object.entries(GOOGLE_CLOUD_PRODUCTS)) { if (queryLower.includes(key) || queryLower.includes(value.name.toLowerCase())) { potentialPaths.push(value.docsPath); } } // Common topic mappings - more specific patterns first const topicMappings: Record<string, string[]> = { // Storage & Encryption encrypt: ["storage/docs/encryption", "kms/docs", "storage/docs/encryption/customer-managed-keys"], "customer managed": ["storage/docs/encryption/customer-managed-keys", "kms/docs/cmek"], share: ["storage/docs/access-control", "iam/docs/granting-changing-revoking-access"], "cross account": ["iam/docs/granting-changing-revoking-access", "storage/docs/access-control/cross-project"], "cross project": ["storage/docs/access-control/cross-project", "iam/docs/granting-changing-revoking-access"], bucket: ["storage/docs/creating-buckets", "storage/docs/access-control", "storage/docs"], "object storage": ["storage/docs", "storage/docs/objects"], permission: ["iam/docs/understanding-roles", "iam/docs/granting-changing-revoking-access"], // IAM & Security iam: ["iam/docs", "iam/docs/understanding-roles"], role: ["iam/docs/understanding-roles", "iam/docs/creating-custom-roles"], kms: ["kms/docs", "kms/docs/quickstart"], cmek: ["storage/docs/encryption/customer-managed-keys", "kms/docs/cmek"], "service account": ["iam/docs/service-accounts", "iam/docs/creating-managing-service-accounts"], impersonat: ["iam/docs/service-account-impersonation", "iam/docs/impersonating-service-accounts"], workload: ["iam/docs/workload-identity-federation", "kubernetes-engine/docs/how-to/workload-identity"], // Networking vpc: ["vpc/docs", "vpc/docs/shared-vpc", "vpc/docs/vpc-peering"], peering: ["vpc/docs/vpc-peering", "vpc/docs/using-vpc-peering"], "shared vpc": ["vpc/docs/shared-vpc", "vpc/docs/provisioning-shared-vpc"], firewall: ["vpc/docs/firewalls", "vpc/docs/using-firewalls"], "load balancer": ["load-balancing/docs", "load-balancing/docs/load-balancing-overview"], ingress: ["kubernetes-engine/docs/concepts/ingress", "load-balancing/docs/https"], ssl: ["load-balancing/docs/ssl-certificates", "certificate-manager/docs"], dns: ["dns/docs", "dns/docs/overview"], "private access": ["vpc/docs/private-google-access", "vpc/docs/configure-private-google-access"], "private service": ["vpc/docs/private-service-connect", "vpc/docs/configure-private-service-connect-services"], nat: ["vpc/docs/nat-service", "vpc/docs/using-nat"], // Database - Cloud SQL "cloud sql": ["sql/docs", "sql/docs/introduction"], "high availability": ["sql/docs/high-availability", "sql/docs/configure-ha"], ha: ["sql/docs/high-availability", "sql/docs/configure-ha"], mysql: ["sql/docs/mysql", "sql/docs/mysql/quickstart"], postgres: ["sql/docs/postgres", "sql/docs/postgres/quickstart"], "sql server": ["sql/docs/sqlserver", "sql/docs/sqlserver/quickstart"], replica: ["sql/docs/replication", "sql/docs/mysql/replication/create-replica"], failover: ["sql/docs/high-availability", "sql/docs/configure-ha"], "read replica": ["sql/docs/replication", "sql/docs/mysql/replication"], "point in time": ["sql/docs/backup-recovery/pitr", "sql/docs/mysql/backup-recovery/pitr"], // BigQuery bigquery: ["bigquery/docs", "bigquery/docs/introduction"], partition: ["bigquery/docs/partitioned-tables", "bigquery/docs/creating-partitioned-tables"], cluster: ["bigquery/docs/clustered-tables", "bigquery/docs/creating-clustered-tables"], "materialized view": ["bigquery/docs/materialized-views-intro", "bigquery/docs/materialized-views-create"], schedule: ["bigquery/docs/scheduling-queries", "bigquery/docs/scheduled-queries"], // GKE & Kubernetes gke: ["kubernetes-engine/docs", "kubernetes-engine/docs/concepts/kubernetes-engine-overview"], kubernetes: ["kubernetes-engine/docs", "kubernetes-engine/docs/quickstart"], autoscal: ["kubernetes-engine/docs/concepts/cluster-autoscaler", "kubernetes-engine/docs/how-to/cluster-autoscaler"], "node pool": ["kubernetes-engine/docs/concepts/node-pools", "kubernetes-engine/docs/how-to/node-pools"], "horizontal pod": ["kubernetes-engine/docs/concepts/horizontalpodautoscaler", "kubernetes-engine/docs/how-to/horizontal-pod-autoscaling"], helm: ["kubernetes-engine/docs/how-to/deploying-workloads-using-helm"], // Serverless "cloud run": ["run/docs", "run/docs/quickstarts"], "environment variable": ["run/docs/configuring/environment-variables", "functions/docs/configuring/env-var"], "cloud function": ["functions/docs", "functions/docs/quickstart"], "app engine": ["appengine/docs", "appengine/docs/standard"], deploy: ["run/docs/deploying", "functions/docs/deploy", "kubernetes-engine/docs/deploy-app-cluster"], // Container & Artifact container: ["run/docs", "kubernetes-engine/docs", "artifact-registry/docs"], docker: ["artifact-registry/docs/docker", "cloud-build/docs/building/build-containers"], "artifact registry": ["artifact-registry/docs", "artifact-registry/docs/docker"], "container registry": ["container-registry/docs"], "cloud build": ["cloud-build/docs", "cloud-build/docs/quickstart-build"], // Secret & Config secret: ["secret-manager/docs", "secret-manager/docs/quickstart"], "secret manager": ["secret-manager/docs", "secret-manager/docs/creating-and-accessing-secrets"], config: ["runtime-config/docs", "deployment-manager/docs"], // Pub/Sub & Messaging pubsub: ["pubsub/docs", "pubsub/docs/overview"], "pub/sub": ["pubsub/docs", "pubsub/docs/overview"], topic: ["pubsub/docs/create-topic", "pubsub/docs/admin"], subscription: ["pubsub/docs/subscriber", "pubsub/docs/create-subscription"], // Data Processing dataflow: ["dataflow/docs", "dataflow/docs/quickstarts"], dataproc: ["dataproc/docs", "dataproc/docs/quickstarts"], composer: ["composer/docs", "composer/docs/quickstart"], airflow: ["composer/docs", "composer/docs/concepts/airflow"], spark: ["dataproc/docs/spark", "dataproc/docs/concepts/spark"], // Monitoring & Logging logging: ["logging/docs", "logging/docs/view/overview"], log: ["logging/docs", "logging/docs/view/logs-viewer-interface"], monitoring: ["monitoring/docs", "monitoring/docs/monitoring-overview"], metric: ["monitoring/docs/metrics", "monitoring/docs/custom-metrics"], alert: ["monitoring/docs/alerting", "monitoring/docs/alerting/policies"], dashboard: ["monitoring/docs/dashboards", "monitoring/docs/dashboards/build-dashboards"], trace: ["trace/docs", "trace/docs/quickstart"], // Infrastructure terraform: ["docs/terraform", "docs/terraform/quickstart"], "deployment manager": ["deployment-manager/docs"], gcloud: ["sdk/gcloud/reference"], "cloud shell": ["shell/docs", "shell/docs/quickstart"], // Misc backup: ["storage/docs/lifecycle", "sql/docs/backup-recovery/backups"], snapshot: ["compute/docs/disks/create-snapshots", "compute/docs/disks/snapshots"], api: ["apis/docs/overview", "endpoints/docs"], authentication: ["docs/authentication", "iam/docs/authentication"], "cloud scheduler": ["scheduler/docs", "scheduler/docs/quickstart"], "cloud tasks": ["tasks/docs", "tasks/docs/quickstart"], budget: ["billing/docs/how-to/budgets", "billing/docs/how-to/budgets-programmatic"], cost: ["billing/docs/how-to/export-data-bigquery", "billing/docs/onboarding-checklist"], }; for (const [keyword, paths] of Object.entries(topicMappings)) { if (queryLower.includes(keyword)) { potentialPaths.push(...paths); } } // Remove duplicates from potential paths const uniquePaths = [...new Set(potentialPaths)]; // Add fallback paths to search results if not already present for (const path of uniquePaths) { const url = `https://cloud.google.com/${path}`; if (!searchResults.some(r => r.url === url)) { searchResults.push({ url, title: path, snippet: "", }); } } // Step 4: Score and sort results by relevance const scoredResults = searchResults.map(item => ({ ...item, score: calculateRelevance(item.url, item.title, query) })); // Sort by score descending scoredResults.sort((a, b) => b.score - a.score); // Filter out results with very low relevance (likely unrelated) const relevantResults = scoredResults.filter(r => r.score >= 0 || scoredResults.indexOf(r) < 3); // Step 5: Fetch content from top results const urlsToFetch = relevantResults.slice(0, 3); for (const item of urlsToFetch) { try { // Extract path from URL const path = item.url.replace("https://cloud.google.com/", "").split("?")[0]; const docResult = await fetchGoogleCloudDoc(path); const parsed = JSON.parse(docResult); if (parsed.error) { results.push({ url: item.url, title: item.title, snippet: item.snippet, error: parsed.error, }); } else { results.push({ url: item.url, title: parsed.title || item.title, snippet: item.snippet, content: parsed.content, }); } } catch (error) { results.push({ url: item.url, title: item.title, snippet: item.snippet, error: error instanceof Error ? error.message : String(error), }); } } // Include other search results without fetching content const otherResults = relevantResults.slice(3, 6).map((item) => ({ url: item.url, title: item.title, snippet: item.snippet, })); return JSON.stringify({ query: query, product: product || "all", totalResults: relevantResults.length, results: results, otherRelatedDocs: otherResults, }); }
• src/index.ts:107-122 (schema)

  Input schema defining parameters: query (string, required), product (string, optional).
  inputSchema: { type: "object" as const, properties: { query: { type: "string", description: "Free-form search query in natural language (e.g., 'how to share encrypted bucket cross account', 'vpc peering between projects', 'cloud sql high availability')", }, product: { type: "string", description: "Optional: Filter by Google Cloud product (e.g., 'compute', 'storage', 'bigquery', 'kubernetes', 'sql', 'run')", }, }, required: ["query"], },
• src/index.ts:55-123 (registration)

  Tool registration in the MCP tools array with name, comprehensive description covering usage triggers, examples, output format, and supported GCP topics.
  { name: "search_google_cloud_docs", description: `Search Google Cloud documentation with any free-form query. Returns relevant documentation with actual content. **WHEN TO USE**: ALWAYS use this tool when the user asks about Google Cloud Platform (GCP) services, configurations, best practices, or how-to questions. This is the PRIMARY tool for GCP-related queries. **TRIGGERS** - Use this tool when user asks about: - Any GCP service (Compute Engine, Cloud Storage, BigQuery, Cloud SQL, GKE, Cloud Run, IAM, VPC, etc.) - Configuration questions ("how to configure...", "how to setup...") - Best practices for GCP services - Troubleshooting GCP issues - Cross-project or cross-account scenarios - Security, encryption, permissions in GCP - Networking in GCP (VPC, peering, firewall, load balancer) - Database configurations (Cloud SQL HA, replicas, backups) - Container orchestration (GKE autoscaling, node pools) - Serverless (Cloud Run, Cloud Functions environment variables) **INPUT**: - query (required): Free-form search query in natural language - product (optional): Filter by specific GCP product **EXAMPLE QUERIES**: - "how to share encrypted bucket cross account" - "vpc peering between two projects" - "cloud sql high availability setup" - "gke autoscaling configuration" - "bigquery partition table" - "cloud run environment variables" - "iam service account impersonation" - "cloud storage cmek encryption" - "gke workload identity" **OUTPUT**: Returns JSON with: - query: Original search query - totalResults: Number of results found - results: Array of top 3 docs with full content (title, url, content) - otherRelatedDocs: Additional related documentation URLs **SUPPORTED TOPICS** (80+ mappings): - Storage & Encryption: encrypt, bucket, cmek, kms, customer managed, object storage - IAM & Security: iam, role, service account, impersonation, workload identity - Networking: vpc, peering, shared vpc, firewall, load balancer, dns, nat, private access - Database: cloud sql, high availability, mysql, postgres, replica, failover - BigQuery: partition, cluster, materialized view, schedule - GKE: gke, autoscaling, node pool, horizontal pod autoscaler, helm - Serverless: cloud run, environment variable, cloud function, deploy - Container: docker, artifact registry, cloud build - Pub/Sub: pubsub, topic, subscription - Data Processing: dataflow, dataproc, composer, airflow, spark - Monitoring: logging, monitoring, metric, alert, dashboard, trace - Infrastructure: terraform, deployment manager, gcloud`, inputSchema: { type: "object" as const, properties: { query: { type: "string", description: "Free-form search query in natural language (e.g., 'how to share encrypted bucket cross account', 'vpc peering between projects', 'cloud sql high availability')", }, product: { type: "string", description: "Optional: Filter by Google Cloud product (e.g., 'compute', 'storage', 'bigquery', 'kubernetes', 'sql', 'run')", }, }, required: ["query"], }, },
• src/index.ts:1050-1056 (handler)

  MCP request handler switch case that parses arguments and invokes the searchGoogleCloudDocs implementation function.
  case "search_google_cloud_docs": { const { query, product } = args as { query: string; product?: string }; const result = await searchGoogleCloudDocs(query, product); return { content: [{ type: "text", text: result }], }; }
• src/index.ts:341-520 (helper)

  Key helper function used by the handler to fetch and parse individual documentation pages into structured markdown content.
  async function fetchGoogleCloudDoc(path: string): Promise<string> { const cleanPath = path.replace(/^\/+/, "").replace(/^cloud\.google\.com\//, ""); const url = `${GOOGLE_CLOUD_API_DOCS_BASE}/${cleanPath}`; try { const response = await fetchWithTimeout(url); if (!response.ok) { return JSON.stringify({ error: `Failed to fetch documentation: HTTP ${response.status}`, url: url, suggestion: "Please check the path and try again. Use 'list_google_cloud_products' to see available products.", }); } const html = await response.text(); const $ = cheerio.load(html); // Remove all unwanted elements $( "script, style, nav, header, footer, noscript, iframe, svg, img, " + ".devsite-nav, .devsite-book-nav, .devsite-footer, .devsite-header, " + ".devsite-breadcrumb-list, .devsite-page-title, .devsite-banner, " + ".devsite-collapsible-section, .devsite-toc, .devsite-article-meta, " + '[role="navigation"], [role="banner"], [aria-hidden="true"], ' + ".nocontent, .caution, .note, .warning, .tip, .key-point, " + ".buttons, .button-group, .cta, .feedback, .rating" ).remove(); // Extract title from h1 or title tag const title = $("h1.devsite-page-title").first().text().trim() || $("article h1").first().text().trim() || $("h1").first().text().trim() || $("title").text().replace(" | Google Cloud", "").trim() || "Google Cloud Documentation"; // Find main content area const mainContent = $(".devsite-article-body").html() || $("article .body-content").html() || $("article").html() || $("main").html() || $(".content").html(); if (!mainContent) { return JSON.stringify({ error: "Could not extract content from the page", url: url, rawTextPreview: $("body").text().replace(/\s+/g, " ").substring(0, 500), }); } const $content = cheerio.load(mainContent); // Remove remaining unwanted elements from content $content( "nav, .devsite-nav, .devsite-toc, .nocontent, " + '[role="navigation"], [aria-hidden="true"]' ).remove(); // Build structured content const sections: { heading: string; content: string; level: number }[] = []; let currentSection = { heading: title, content: "", level: 1 }; // Process each element in order $content("h1, h2, h3, h4, h5, p, pre, ul, ol, table, blockquote, dl").each((_, elem) => { const $elem = $content(elem); const tagName = elem.type === "tag" ? elem.name : ""; // Skip empty elements const text = $elem.text().trim(); if (!text) return; // Skip navigation-like content if (text.includes("Documentation") && text.includes("Home") && text.length < 100) return; if (text.startsWith("Stay organized with collections")) return; if (text.startsWith("Save and categorize")) return; if (["h1", "h2", "h3", "h4", "h5"].includes(tagName)) { // Save previous section if it has content if (currentSection.content.trim()) { sections.push({ ...currentSection }); } currentSection = { heading: text, content: "", level: parseInt(tagName.substring(1)), }; } else if (tagName === "pre") { // Code blocks const codeText = $elem.text().trim(); if (codeText && codeText.length > 5) { // Detect language from class const codeClass = $elem.find("code").attr("class") || ""; const lang = codeClass.match(/language-(\w+)/)?.[1] || ""; currentSection.content += `\n\`\`\`${lang}\n${codeText}\n\`\`\`\n`; } } else if (tagName === "table") { // Extract table data const rows: string[] = []; $elem.find("tr").each((_, tr) => { const cells: string[] = []; $content(tr).find("th, td").each((_, cell) => { cells.push($content(cell).text().trim()); }); if (cells.length > 0) { rows.push(cells.join(" | ")); } }); if (rows.length > 0) { currentSection.content += `\n| ${rows.join(" |\n| ")} |\n`; } } else if (tagName === "ul" || tagName === "ol") { // Lists const items: string[] = []; $elem.children("li").each((i, li) => { const itemText = $content(li).text().trim(); if (itemText) { const prefix = tagName === "ol" ? `${i + 1}.` : "-"; items.push(`${prefix} ${itemText}`); } }); if (items.length > 0) { currentSection.content += `\n${items.join("\n")}\n`; } } else if (tagName === "dl") { // Definition lists $elem.find("dt").each((_, dt) => { const term = $content(dt).text().trim(); const dd = $content(dt).next("dd").text().trim(); if (term) { currentSection.content += `\n**${term}**: ${dd}\n`; } }); } else if (tagName === "blockquote") { currentSection.content += `\n> ${text}\n`; } else { // Paragraphs and other text if (text.length > 10) { currentSection.content += `\n${text}\n`; } } }); // Push last section if (currentSection.content.trim()) { sections.push(currentSection); } // Format output as markdown const formattedContent = sections .filter(s => s.content.trim().length > 0) .map((s) => { const headingPrefix = "#".repeat(Math.min(s.level, 4)); return `${headingPrefix} ${s.heading}\n${s.content.trim()}`; }) .join("\n\n"); // Clean up excessive whitespace const cleanContent = formattedContent .replace(/\n{3,}/g, "\n\n") .trim(); return JSON.stringify({ title: title, url: url, content: cleanContent.substring(0, 20000), contentLength: cleanContent.length, truncated: cleanContent.length > 20000, }); } catch (error) { const errorMessage = error instanceof Error ? error.message : String(error); return JSON.stringify({ error: `Failed to fetch documentation: ${errorMessage}`, url: url, }); } }