Clients

hypequery MCP runs over stdio, so your MCP client launches the server. There are two ways to launch it:

• hypequery mcp serves the datasets in your Serve API file. The command must run from your project directory, so the client config changes into it first.
• @hypequery/mcp --config runs the standalone server with a dedicated config file.

Claude Desktop with hypequery mcp

Add a server entry to Claude Desktop's config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "hypequery": {
      "command": "sh",
      "args": ["-c", "cd /absolute/path/to/your-project && npx hypequery mcp"],
      "env": {
        "CLICKHOUSE_URL": "https://example.clickhouse.cloud:8443",
        "CLICKHOUSE_USERNAME": "default",
        "CLICKHOUSE_PASSWORD": "password",
        "CLICKHOUSE_DATABASE": "analytics"
      }
    }
  }
}

On Windows, use "command": "cmd" with "args": ["/c", "cd /d C:\\path\\to\\your-project && npx hypequery mcp"]. Add --tenant <id> to the command if any dataset is tenant-scoped. Cursor accepts the same command, args, and env in its MCP configuration.

Restart Claude Desktop after changing the config.

A Python API with hypequery mcp

The Python CLI prints the entry for you, with the project's interpreter and directory as absolute paths:

hypequery mcp app:api --print-config

{
  "mcpServers": {
    "hypequery": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["-m", "hypequery", "mcp", "app:api", "--project", "/absolute/path/to/your-project"],
      "env": { "HYPEQUERY_API_KEY": "${HYPEQUERY_API_KEY}" }
    }
  }
}

env appears when a credential is configured; replace the placeholder with the key, or keep it in clients that expand environment variables. The ClickHouse settings come from the project's .env, as for hypequery dev.

Standalone server

Claude Desktop

To run the standalone server instead, point the client at your config file:

{
  "mcpServers": {
    "hypequery": {
      "command": "npx",
      "args": [
        "-y",
        "@hypequery/mcp",
        "--config",
        "/absolute/path/to/mcp-config.mjs"
      ],
      "env": {
        "CLICKHOUSE_URL": "https://example.clickhouse.cloud:8443",
        "CLICKHOUSE_USERNAME": "default",
        "CLICKHOUSE_PASSWORD": "password",
        "CLICKHOUSE_DATABASE": "analytics"
      }
    }
  }
}

Restart Claude Desktop after changing the config.

Cursor

Use the same command and arguments in Cursor's MCP configuration:

{
  "mcpServers": {
    "hypequery": {
      "command": "npx",
      "args": [
        "-y",
        "@hypequery/mcp",
        "--config",
        "/absolute/path/to/mcp-config.mjs"
      ],
      "env": {
        "CLICKHOUSE_URL": "https://example.clickhouse.cloud:8443",
        "CLICKHOUSE_USERNAME": "default",
        "CLICKHOUSE_PASSWORD": "password",
        "CLICKHOUSE_DATABASE": "analytics"
      }
    }
  }
}

Test the server directly

Before connecting a client, check a hypequery mcp setup from your project directory. It loads the API file and reports the datasets it would serve, without starting the server:

npx hypequery mcp --self-test

For the standalone server, run it from a terminal:

npx -y @hypequery/mcp --config /absolute/path/to/mcp-config.mjs

You should see startup logs on stderr. The process keeps running because the MCP client normally owns its lifecycle.