yatharthagoenka/gcp-iam-recommender

GCP IAM Role Recommender MCP Server

An MCP (Model Context Protocol) server that helps users discover and analyze the least privilege IAM roles needed to perform specific actions on Google Cloud Platform.

Overview

This server provides:

1. Interactive Project ID Prompt: Ask users for their GCP project ID with helpful guidance
2. Query Grantable Roles: Analyze all available IAM roles for a GCP project and recommend the minimum permissions needed for a specific action
3. Fetch All Roles: Retrieve and cache all GCP IAM roles for analysis

Prerequisites

• Go 1.24 or later
• Google Cloud SDK (gcloud) installed and authenticated
• Proper GCP project access and permissions

Installation

1. Clone or navigate to this directory
2. Install dependencies:

   go mod tidy
   

3. Build the server:

   make build
   

Configuration

The server uses Google Cloud Application Default Credentials. Make sure you're authenticated:

gcloud auth application-default login

Available Prompts

get_project_id

Interactively asks the user for their GCP project ID with helpful guidance on how to find it.

Parameters:

• action (optional): The action the user wants to perform (provides context)

Example:

{
  "name": "get_project_id",
  "arguments": {
    "action": "add new secret value to secret manager"
  }
}

The prompt will guide users to find their project ID using:

• gcloud config get-value project
• Google Cloud Console
• gcloud projects list

Available Tools

1. query_grantable_roles

Queries all grantable IAM roles for a specified GCP project and provides intelligent recommendations based on the action you want to perform.

Parameters:

• project_id (required): The GCP project ID to query roles for
• action_description (required): Description of what you want to do (e.g., "deploy cloud function", "read storage bucket")

Example:

{
  "name": "query_grantable_roles",
  "parameters": {
    "project_id": "my-gcp-project",
    "action_description": "deploy cloud functions and read from storage buckets"
  }
}

The tool will:

• List all grantable roles for the project
• Analyze your action description using keyword matching
• Recommend the most appropriate least-privilege roles
• Provide a comprehensive table of all available roles

2. fetch_all_roles

Fetches all IAM roles from Google Cloud and caches them locally for faster analysis.

Parameters:

• force_refresh (optional): Set to 'true' to force refresh the cache even if it exists

Example:

{
  "name": "fetch_all_roles",
  "parameters": {
    "force_refresh": "false"
  }
}

This tool will:

• Fetch all available IAM roles from Google Cloud
• Cache them locally for improved performance
• Provide a summary of fetched roles

3. get_instructions

Get instructions for the AI agent to choose the right IAM roles. This tool provides guidelines for selecting least-privilege roles.

Workflow Example

Role Discovery Workflow

1. Discover what you need:

   # Use the MCP tool through Cursor or direct API call
   query_grantable_roles(
     project_id="my-project", 
     action_description="deploy cloud functions"
   )
   

2. Get recommendations: The tool analyzes your action and recommends roles like:

   • roles/cloudfunctions.developer
   • roles/storage.objectViewer (if functions need storage access)
   • roles/logging.logWriter (for function logs)

3. Use the recommended roles: You can then use these role recommendations to:

   • Configure IAM policies in your infrastructure as code
   • Request appropriate permissions from your admin
   • Set up service accounts with minimal privileges

Intelligent Role Analysis

The server includes intelligent keyword analysis to recommend appropriate roles:

GCP IAM Roles by Service:

• Storage/GCS: storage.objectViewer, storage.objectCreator, storage.objectAdmin
• Compute/VM: compute.viewer, compute.instanceAdmin, compute.admin
• GKE/Kubernetes: container.viewer, container.clusterViewer, container.clusterAdmin
• Cloud Functions: cloudfunctions.viewer, cloudfunctions.developer, cloudfunctions.admin
• Cloud Run: run.viewer, run.developer, run.admin
• Cloud SQL: cloudsql.viewer, cloudsql.client, cloudsql.admin
• Pub/Sub: pubsub.viewer, pubsub.subscriber, pubsub.publisher, pubsub.admin
• IAM: iam.roleViewer, iam.securityReviewer, iam.roleAdmin
• Secrets: secretmanager.viewer, secretmanager.secretAccessor, secretmanager.admin

Building and Running

# Build the server
make build

# Run the server locally
make run

# Install globally to PATH as 'gcp-iam-server'
make install

# Uninstall from PATH
make uninstall

# Clean build artifacts
make clean

After running make install, the binary will be available as gcp-iam-server from anywhere in your system.

Project Structure

.
├── bin/                 # Compiled binaries
├── cmd/
│   ├── main.go         # Main application entry point
│   └── tools/          # MCP tool implementations
│       ├── query_grantable_roles.go
│       └── fetch_roles.go
├── Makefile            # Build commands
├── README.md           # This file
└── go.mod              # Go module definition

Error Handling

The server provides clear error messages for common issues:

• Invalid or non-existent project IDs
• Authentication failures
• Network connectivity issues
• Missing cached role data

Security Considerations

• The server follows the principle of least privilege
• Role recommendations prioritize minimal necessary permissions
• All analysis is performed locally with cached role data
• The server validates project access before making recommendations

Integration with Cursor

This MCP server is designed to work seamlessly with Cursor IDE:

1. The server uses the MCP protocol for natural language interaction
2. Provides rich, formatted output with emoji and markdown
3. Includes comprehensive error handling and user guidance
4. Supports both interactive queries and programmatic usage

Cursor MCP Server Configuration

To use this GCP IAM server with Cursor, add the following configuration to your Cursor settings:

1. Open Cursor Settings: Go to Cursor → Settings → Features → MCP Servers
2. Add the configuration (choose one of the following approaches):

Option A: Using environment variable (Recommended)

{
  "mcpServers": {
    "gcp-iam": {
      "name": "GCP IAM Recommender",
      "command": "${MCP_SERVERS_PATH}/iam/bin/server"
    }
  }
}

Set the environment variable in your shell:

export MCP_SERVERS_PATH="/path/to/your/mcp-servers"

Option B: Using relative path from home directory

{
  "mcpServers": {
    "gcp-iam": {
      "name": "GCP IAM Recommender",
      "command": "~/path/to/gcp-iam-recommender/bin/server"
    }
  }
}

Option C: Install globally and use binary name

{
  "mcpServers": {
    "gcp-iam": {
      "name": "GCP IAM Recommender",
      "command": "gcp-iam-server"
    }
  }
}

For Option C, install the server globally:

make install  # This should install the binary to your PATH

Important Notes:

• Choose the option that best fits your setup
• Make sure the server binary is built using make build before adding this configuration
• The server will automatically cache IAM roles for improved performance
• Authenticate with Google Cloud using gcloud auth application-default login

3. Restart MCP for the changes to take effect

4. Usage in Cursor: Once configured, you can interact with the server naturally:

   • "What IAM role do I need to delete records from Datastore?"
   • "Find roles for deploying Cloud Functions"
   • "Get least privilege roles for reading from Storage buckets"

The server will provide intelligent recommendations based on your action descriptions and help you understand the exact permissions needed for your GCP tasks.

Troubleshooting

Common Issues

1. Authentication errors:

   # Re-authenticate with Google Cloud
   gcloud auth application-default login
   

2. Project access denied:

   • Ensure you have the necessary permissions to view IAM roles for the project
   • Verify the project ID is correct and active

3. Missing role cache:

   • Use the fetch_all_roles tool to populate the role cache
   • Ensure you have internet connectivity to fetch from Google Cloud