gcloud MCP Server

A high-performance Model Context Protocol (MCP) server that provides intelligent access to Google Cloud CLI (gcloud) commands and documentation.

Features

• Fast Command Search: O(k) trie-based lookups for exact command paths
• Intelligent Text Search: Inverted index with TF-IDF scoring for description searches
• 4 Powerful Tools: Search commands, get details, search flags, suggest commands
• High Performance: <50ms queries, <2s startup, <500MB memory
• Comprehensive Coverage: 5,907 commands and 12,374 flags indexed

Performance Metrics ✅

• Loading Time: 1,775ms (target: <2,000ms)
• Memory Usage: 99MB (target: <500MB)
• Search Speed: 30ms (target: <50ms)
• Trie Lookups: 0ms (target: <5ms)

Installation

For Claude Code Users (Primary Method)

The easiest way to install is using the Claude Code MCP command:

claude mcp add gcloud-mcp -s user -- npx gcloud-mcp

This will automatically:

1. Use the npm package via npx (no global install needed)
2. Add the server to your Claude Code configuration
3. Make it available in all your Claude Code sessions

Alternative: Manual Installation

Global Installation

npm install -g gcloud-mcp

Then add to your Claude Desktop configuration:

{
  "mcpServers": {
    "gcloud-mcp": {
      "command": "gcloud-mcp",
      "env": {}
    }
  }
}

Local Installation

npm install gcloud-mcp

Then add to your Claude Desktop configuration:

{
  "mcpServers": {
    "gcloud-mcp": {
      "command": "npx",
      "args": ["gcloud-mcp"],
      "env": {}
    }
  }
}

Prerequisites

• Node.js 18.0.0 or higher

How It Works

The server includes a comprehensive gcloud command index (gcloud.json) with:

• 5,907 gcloud commands
• 12,374 command flags
• Complete documentation and examples

This data is automatically loaded when the server starts, providing instant access to gcloud CLI information without requiring the gcloud CLI to be installed.

Direct Usage

node build/index.js

MCP Tools

1. search_commands

Search for gcloud commands using keywords or descriptions.

Parameters:

• query (string): Search term
• maxResults (number, optional): Maximum results (default: 10)
• searchType (string, optional): 'exact', 'prefix', 'description', 'all' (default: 'all')
• includeHidden (boolean, optional): Include hidden commands (default: false)

Example:

{
  "query": "compute instances create",
  "maxResults": 5,
  "searchType": "all"
}

2. get_command_details

Get comprehensive information about a specific gcloud command.

Parameters:

• commandPath (string): Full command path (e.g., "compute instances create")

Example:

{
  "commandPath": "compute instances create"
}

3. search_flags

Search for gcloud flags by name, description, or functionality.

Parameters:

• query (string): Search term
• maxResults (number, optional): Maximum results (default: 20)
• commandContext (string, optional): Filter by command context
• flagType (string, optional): Filter by flag type
• includeGlobal (boolean, optional): Include global flags (default: true)

Example:

{
  "query": "zone",
  "maxResults": 10,
  "commandContext": "compute"
}

4. suggest_command

Get AI-powered command suggestions based on user intent.

Parameters:

• userIntent (string): Description of what the user wants to accomplish
• maxSuggestions (number, optional): Maximum suggestions (default: 5)
• includeFlags (boolean, optional): Include relevant flags (default: true)

Example:

{
  "userIntent": "create a virtual machine in us-west1",
  "maxSuggestions": 3,
  "includeFlags": true
}

MCP Resources

gcloud://server/stats

Server performance and indexing statistics in JSON format.

gcloud://cli/version

gcloud CLI version and indexing information in plain text.

Architecture

Data Structures

• CommandTrie: O(k) command path lookups using trie data structure
• InvertedIndex: Full-text search with TF-IDF scoring for descriptions
• FlagsMap: Fast flag lookups by name

Core Components

• GcloudDataLoader: Loads and indexes 35.7MB gcloud.json file
• Search Tools: 4 specialized MCP tools for different search patterns
• Performance Optimizations: Efficient memory usage and fast query responses

Project Structure

├── src/
│   ├── index.ts                 # Main MCP server entry point
│   ├── lib/
│   │   ├── gcloud-loader.ts     # Data loading and indexing
│   │   ├── trie.ts              # Trie data structure for commands
│   │   └── inverted-index.ts    # Full-text search index
│   ├── tools/
│   │   ├── search-commands.ts   # Command search tool
│   │   ├── get-command-details.ts # Command details tool
│   │   ├── search-flags.ts      # Flag search tool
│   │   └── suggest-command.ts   # AI suggestion tool
│   └── types/
│       └── gcloud.ts            # TypeScript type definitions
├── build/                       # Compiled JavaScript output
├── gcloud.json                  # gcloud CLI command data (35.7MB)
├── package.json                 # Project configuration
├── tsconfig.json               # TypeScript configuration
└── README.md                   # This file

Development

Scripts

• npm run build: Compile TypeScript to JavaScript
• npm run dev: Development mode with file watching

Dependencies

• @modelcontextprotocol/sdk: MCP protocol implementation
• fuse.js: Fuzzy search capabilities
• zod: Runtime type validation

Performance Characteristics

Memory Usage

• Base server: ~99MB RAM
• Indexed data: 21,352 unique search terms
• Command trie: 5,907 indexed commands

Search Performance

• Exact lookups: 0ms (trie-based)
• Description search: ~30ms (inverted index)
• Startup time: 1,775ms (one-time cost)

License

MIT License - see LICENSE file for details.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Submit a pull request

Support

For issues and questions:

• Open an issue on GitHub
• Check the documentation for usage examples
• Review the performance metrics for optimization guidance