CloudQuery MCP Server

A Model Context Protocol (MCP) server that provides access to CloudQuery asset inventory data.

Prerequisites

• Claude Desktop, Cursor IDE or any other tool capable of using MCP servers.
• If you're using it against CloudQuery Platform, a non-expired CloudQuery Platform API Key and the URL of the deployment it is valid for.
• If you're using it against a PostgreSQL destination (from one or more CloudQuery syncs), the PostgreSQL connection string.

Installation

Download Binary

Download the latest binary for your platform from the Releases page.

macOS Security Note

On macOS, you may encounter a security warning when running the binary for the first time. This is because the binary is not signed with an Apple Developer certificate. To bypass this:

Option 1 (Recommended): Use the command line to remove the quarantine attribute:

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

Option 2: Go to System Preferences > Security & Privacy > General, and click "Allow Anyway" for the blocked app.

Supported modes

The MCP server supports three modes:

• cli - for getting started with CloudQuery CLI and generate configuration files using natural language
• postgres - for CLI users syncing to a PostgreSQL destination, to query the data synced to the database using natural language
• platform - for CloudQuery Platform customers to query the data synced to the platform using natural language

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

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

The MCP server supports reading .env files.

Optional Environment Variables

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

Claude Desktop Integration

Configure Claude Desktop by editing the config file at $HOME/Library/Application\ Support/Claude/claude_desktop_config.json on MacOS or $HOME/.config/Claude/claude_desktop_config.json on Linux:

If you're using it against CloudQuery Platform:

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

If you're using it against a PostgreSQL destination, e.g.:

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

Notes:

• "command" must be an absolute path to your local cq-platform-mcp binary.

Example: "/home/username/cq-platform-mcp" or "/Users/username/cq-platform-mcp"

Cursor IDE Integration

Configure Cursor IDE by adding the MCP server configuration to your settings:

1. Open Cursor IDE
2. Go to Settings > Cursor Settings > Tools and Integrations
3. Add a new MCP server with the following configuration:

{
  "mcpServers": {
    "cloudquery": {
      "command": "/path/to/mcp/binary",
      "args": [],
      "env": {
        "CQ_PLATFORM_API_KEY": "your_api_key_here",
        "CQ_PLATFORM_API_URL": "https://your-instance.cloudquery.io/api"
      }
    }
  }
}

If you're using it against a PostgreSQL destination, e.g.:

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

VSCode IDE Integration

There are multiple ways to integrate MCP servers in VSCode, as described in the VSCode MCP documentation. A summary of the steps to integrate the CloudQuery MCP server in VSCode is:

1. Open VSCode 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:

If you're using it against CloudQuery Platform:

{
  "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/mcp/binary",
      "env":{
        "CQ_PLATFORM_API_KEY": "${input:cloudquery-platform-api-key}",
        "CQ_PLATFORM_API_URL": "${input:cloudquery-platform-api-url}"
      }
    }
  }
}

If you're using it against a PostgreSQL destination, e.g.:

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

To see the new MCP server in the list, you might need to restart VSCode.

On first use, you will be prompted to enter the API key and API URL, or the PostgreSQL connection string.

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.