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.
If you’re not a CloudQuery Platform customer but you are a CLI user, you can still use the CloudQuery MCP server in CLI or PostgreSQL Mode.
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
- Open Cursor
- Go to Settings → Cursor Settings → Tools and Integrations
- 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:
- Open VSCode IDE
- Go to
MCP: Open User Configuration
(can also be done at the workspace or folder level) via the keyboard shortcutCtrl+Shift+P
(Windows/Linux) orCmd+Shift+P
(Mac) - 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.