CloudQuery MCP Server

The CloudQuery MCP (Model Context Protocol) Server lets you query your CloudQuery asset inventory using Claude Desktop, Cursor IDE, or any LLM tool that supports the MCP protocol. To explore findings through the platform UI instead, see Insights.

There are two ways to connect:

• Hosted MCP server – for CloudQuery Platform customers. Your platform serves the MCP endpoint itself, so there is nothing to install.
• Local MCP binary – a binary you run on your machine. Use it if you are a CLI user, or if your client can only start a local process.

Hosted MCP server

Enable it

An admin turns the server on once for the organization: go to Settings → Organization → MCP server and switch on Enable the MCP server for this organization. The page then shows the endpoint URL and ready-to-copy snippets for your deployment.

The endpoint is your platform URL followed by /mcp, for example https://your-deployment.cloudquery.io/mcp.

Option 1: Sign in with your CloudQuery account (recommended)

Use this for clients that can open a browser, such as Claude Code, Claude Desktop, claude.ai and ChatGPT. The first time you connect, the client opens a browser. You sign in the way you already do and approve access. The client then keeps a token that refreshes itself, so there is no key to copy or rotate.

Each person signs in as themselves and can only read what their roles allow. On the approval screen you can choose Read only to hide every tool that changes data, whatever your role allows.

Claude Code

claude mcp add --transport http cloudquery https://your-deployment.cloudquery.io/mcp

Claude Desktop, claude.ai and ChatGPT

Add a custom connector in the client’s settings and paste the endpoint URL. In Claude, go to Settings → Connectors → Add custom connector. On a Team or Enterprise plan, an organization Owner adds it once for everyone.

https://your-deployment.cloudquery.io/mcp

Other clients with a configuration file

Claude Desktop does not accept this entry, because its configuration file only runs local servers.

{
  "mcpServers": {
    "cloudquery": {
      "type": "http",
      "url": "https://your-deployment.cloudquery.io/mcp"
    }
  }
}

Option 2: Connect with an API key

Use this for clients that cannot open a browser to sign in, such as Cursor, or unattended clients such as CI jobs. Create a key on the API keys page and send it as a static Authorization header.

Claude Code

claude mcp add --transport http cloudquery https://your-deployment.cloudquery.io/mcp \
  --header "Authorization: Bearer <YOUR_API_KEY>"

Configuration file

{
  "mcpServers": {
    "cloudquery": {
      "type": "http",
      "url": "https://your-deployment.cloudquery.io/mcp",
      "headers": { "Authorization": "Bearer <YOUR_API_KEY>" }
    }
  }
}

Local MCP binary

The binary supports four operating modes:

• CLI Mode – for getting started with CloudQuery CLI and generating configuration files using natural language
• Platform Mode – for CloudQuery Platform customers whose client can only start a local process. When the hosted MCP server is enabled, the binary forwards to it and exposes the same tools.
• PostgreSQL Mode – for CLI users syncing to a PostgreSQL destination
• Snowflake Mode – for CLI users syncing to a Snowflake destination (Requires MCP server >= 1.8.0)

Quick Start

Download the latest version of the MCP binary for your platform.

Unzip the binary and ensure it’s executable.

Requirements

CLI Mode

The default mode and available to all users.

Tools

Platform Mode

This mode is for CloudQuery Platform customers. You’ll need:

• Your CloudQuery Platform API Key
• Your deployment’s API URL

Tools

PostgreSQL Mode

This mode is available to all CloudQuery CLI users who sync to a PostgreSQL destination. You’ll need:

• The Connection String or DSN to the PostgreSQL database

Tools

The MCP server must be able to reach the PostgreSQL database from its host.

Snowflake Mode (Requires MCP server >= 1.8.0)

This mode is available to all CloudQuery CLI users who sync to a Snowflake destination. You’ll need:

• The Snowflake connection string in the format: user:password@account/database/schema?warehouse=warehouse_name

Tools

The MCP server must be able to reach the Snowflake database from its host.

Environment Variables

CLI Mode

If no environment variables are set, the MCP server will default to CLI mode.

PostgreSQL Mode

Configure the following environment variables to enable PostgreSQL mode.

• POSTGRES_CONNECTION_STRING - postgres://user:password@host:port/database

If no search_path is specified in the connection string, the MCP server automatically defaults to public schema. You can override this by explicitly setting search_path in your connection string (e.g., postgres://user:password@host:port/database?search_path=myschema).

The MCP server supports reading .env files.

Kerberos Authentication

For Kerberos/GSSAPI authentication, include the appropriate parameters in the connection string:

• postgres://[email protected]@host:port/database?krbsrvname=postgres
• postgres://username@host:port/database?krbsrvname=postgres&gsslib=gssapi

Snowflake Mode (Requires MCP server >= 1.8.0)

Configure the following environment variables to enable Snowflake mode.

• SNOWFLAKE_CONNECTION_STRING - Snowflake connection string in the format: user:password@account/database/schema?warehouse=warehouse_name

Example connection strings:

• user:password@account/database/schema - Basic authentication
• user:password@account/database/schema?warehouse=COMPUTE_WH - With warehouse specified
• user:[email protected]/database/schema?warehouse=COMPUTE_WH - With region

For more connection string options, see the Snowflake Go Driver documentation.

The MCP server supports reading .env files.

Platform Mode

Configure the following environment variables to enable Platform mode.

• CQ_PLATFORM_API_URL - https://your-deployment.cloudquery.io/api
• CQ_PLATFORM_API_KEY - Your CloudQuery Platform API key

Optional

• CQAPI_LOG_LEVEL: Log level (debug, info, warn, error, default: info)
• LOG_PRETTY: Enable pretty console logging (auto-detected by default)
• LOG_COLOR: Enable colored logging (auto-detected by default)

You can place these in a .env file or export them in your shell.

IDE Integration

Claude Desktop

Add the following configuration to:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

CLI Mode

{
  "mcpServers": {
    "cloudquery": {
      "command": "/absolute/path/to/cq-platform-mcp",
      "args": [],
      "env": {}
    }
  }
}

Platform Mode

{
  "mcpServers": {
    "cloudquery": {
      "command": "/absolute/path/to/cq-platform-mcp",
      "args": [],
      "env": {
        "CQ_PLATFORM_API_KEY": "your_api_key",
        "CQ_PLATFORM_API_URL": "https://your-deployment.cloudquery.io/api"
      }
    }
  }
}

PostgreSQL Mode

{
  "mcpServers": {
    "cloudquery": {
      "command": "/absolute/path/to/cq-platform-mcp",
      "args": [],
      "env": {
        "POSTGRES_CONNECTION_STRING": "postgres://user:pass@localhost:5432/db?sslmode=disable"
      }
    }
  }
}

Snowflake Mode (Requires MCP server >= 1.8.0)

{
  "mcpServers": {
    "cloudquery": {
      "command": "/absolute/path/to/cq-platform-mcp",
      "args": [],
      "env": {
        "SNOWFLAKE_CONNECTION_STRING": "user:password@account/database/schema?warehouse=COMPUTE_WH"
      }
    }
  }
}

The "command" must be an absolute path to the binary.

Cursor IDE

1. Open Cursor
2. Go to Settings → Cursor Settings → Tools and Integrations
3. Add a new MCP server configuration:

Platform Mode Example

{
  "name": "cloudquery",
  "command": "/path/to/cq-platform-mcp",
  "args": [],
  "env": {
    "CQ_PLATFORM_API_KEY": "your_api_key",
    "CQ_PLATFORM_API_URL": "https://your-deployment.cloudquery.io/api"
  }
}

PostgreSQL Mode Example

{
  "name": "cloudquery",
  "command": "/path/to/cq-platform-mcp",
  "args": [],
  "env": {
    "POSTGRES_CONNECTION_STRING": "postgres://user:password@localhost:5432/database?sslmode=disable"
  }
}

Snowflake Mode Example (Requires MCP server >= 1.8.0)

{
  "name": "cloudquery",
  "command": "/path/to/cq-platform-mcp",
  "args": [],
  "env": {
    "SNOWFLAKE_CONNECTION_STRING": "user:password@account/database/schema?warehouse=COMPUTE_WH"
  }
}

VS Code IDE Integration

There are multiple ways to integrate MCP servers in VS Code, as described in the VS Code MCP documentation.

1. Open VS Code IDE
2. Go to MCP: Open User Configuration (can also be done at the workspace or folder level) via the keyboard shortcut Ctrl+Shift+P (Windows/Linux) or Cmd+Shift+P (Mac)
3. Add a new MCP server with the following configuration:

CLI Mode

{
  "servers": {
    "CloudQuery": {
      "type": "stdio",
      "command": "/path/to/cq-platform-mcp",
      "env": {}
    }
  }
}

Platform Mode

{
  "inputs":[
    {
      "type":"promptString",
      "id":"cloudquery-platform-api-key",
      "description":"CloudQuery Platform API Key",
      "password":true
    },
    {
      "type":"promptString",
      "id":"cloudquery-platform-api-url",
      "description":"CloudQuery Platform API URL",
      "password":false
    }
  ],
  "servers":{
    "CloudQuery":{
      "type":"stdio",
      "command": "/path/to/cq-platform-mcp",
      "env":{
        "CQ_PLATFORM_API_KEY": "${input:cloudquery-platform-api-key}",
        "CQ_PLATFORM_API_URL": "${input:cloudquery-platform-api-url}"
      }
    }
  }
}

PostgreSQL Mode

{
  "inputs":[
    {
      "type":"promptString",
      "id":"cloudquery-postgres-connection-string",
      "description":"CloudQuery PostgreSQL Connection String",
      "password":true
    }
  ],
  "servers":{
    "CloudQuery":{
      "type":"stdio",
      "command": "/path/to/cq-platform-mcp",
      "env":{
        "POSTGRES_CONNECTION_STRING": "${input:cloudquery-postgres-connection-string}"
      }
    }
  }
}

Snowflake Mode (Requires MCP server >= 1.8.0)

{
  "inputs":[
    {
      "type":"promptString",
      "id":"cloudquery-snowflake-connection-string",
      "description":"CloudQuery Snowflake Connection String",
      "password":true
    }
  ],
  "servers":{
    "CloudQuery":{
      "type":"stdio",
      "command": "/path/to/cq-platform-mcp",
      "env":{
        "SNOWFLAKE_CONNECTION_STRING": "${input:cloudquery-snowflake-connection-string}"
      }
    }
  }
}

macOS Security Note

If macOS blocks the binary, use:

xattr -d com.apple.quarantine /absolute/path/to/cq-platform-mcp

Or allow it in System Preferences → Security & Privacy → General.

Streamable HTTP Server

The MCP server can also be run as a Streamable HTTP server, which allows you to connect to it remotely. To enable this, set the HTTP_ADDRESS environment variable to the desired address and port, e.g.:

export HTTP_ADDRESS=":8080"

The server will then listen for incoming HTTP requests under the path /mcp on the specified address and port.

About MCP

MCP (Model Context Protocol) is a standard for tools like Claude Desktop to interact with external structured data sources. The CloudQuery MCP Server exposes your asset inventory to these tools.

Next Steps

• AI Assistant - Built-in conversational agent under Ask AI in the sidebar with optional full data access
• AI Assistant in the SQL Console - Generate SQL from natural language inside the SQL Console
• SQL Console - Run queries directly in the platform
• API Keys - Generate API keys for MCP server authentication