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.

This server supports three operating modes:

• CLI Mode – for getting started with CloudQuery CLI and generate configuration files using natural language
• Platform Mode – for CloudQuery Platform customers
• PostgreSQL Mode – for CLI users syncing to a PostgreSQL destination

🚀 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.

Platform Mode

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

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

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

Note: The MCP server must be able to reach the Postgres database from where it is running.

⚙️ 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

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 config 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-mcp",
      "args": [],
      "env": {}
    }
  }
}

Platform Mode

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

Postgres Mode

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

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-mcp",
  "args": [],
  "env": {
    "CQ_PLATFORM_API_KEY": "your_api_key",
    "CQ_PLATFORM_API_URL": "https://your-deployment.cloudquery.io/api"
  }
}

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:

CLI Mode

{
  "servers": {
    "CloudQuery": {
      "type": "stdio",
      "command": "/path/to/cq-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-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 Postgres Connection String",
      "password":true
    }
  ],
  "servers":{
    "CloudQuery":{
      "type":"stdio",
      "command": "/path/to/cq-mcp",
      "env":{
        "POSTGRES_CONNECTION_STRING": "${input:cloudquery-postgres-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.