hex-mcp MCP server

A MCP server for Hex that implements orchestration, monitoring, cell content access, permission management, collection organization, and group management tools.

What This Does (And Doesn't Do)

Practical Use Cases

Orchestration and Automation:
- Trigger Hex project runs from external systems (Airflow DAGs, CI/CD pipelines)
- Monitor run status programmatically
- Cancel long-running or stuck executions
- Discover and search projects across workspaces

Operational Monitoring:
- Check if scheduled runs completed successfully
- Get run history for auditing
- Programmatic access to project metadata (owner, last edited, description)

Cell Content Access (NEW):
- Read notebook structure and cell metadata
- Read SQL query source code from SQL cells
- Read Python/R code from CODE cells
- Good for query migration, code analysis, and content auditing

Permission Management (NEW):
- Programmatically manage user and group access to projects
- Bulk update permissions across multiple projects
- Manage workspace-wide and public access settings
- Add or remove projects from collections

Collection Organization (NEW):
- Create and manage collections for organizing projects
- Organize projects by department, team, or topic
- Control collection visibility and access
- Bulk organize projects into collections

Group Management (NEW):
- Create and manage user groups for permission management
- Add and remove users from groups in bulk
- Use groups to simplify permission management across projects
- Maintain organized team structures

Data Connection Management (NEW):
- List and manage database and warehouse connections
- Create connections for BigQuery, Snowflake, Postgres, Redshift, Athena, Databricks
- Update connection configurations and credentials
- Control data connection sharing across workspace

Critical Limitations

Limited notebook content access:
- ✅ Can read SQL and CODE cell source content
- ❌ Cannot read MARKDOWN, INPUT, or visualization cells
- ❌ Cannot create or delete cells
- ❌ Cannot modify notebook structure
- ❌ Cannot view query results or charts
- ❌ Cannot manage notebook dependencies or parameters

Not suitable for:
- Building or authoring notebooks from scratch
- Collaborative notebook development
- Debugging queries or code execution
- Full notebook backup (only SQL/CODE cells accessible)
- Reading markdown documentation or input parameters

When to Use This

Use hex-mcp when you need to:
- Orchestrate Hex executions from external systems
- Monitor run status and history
- Read SQL queries and code from existing notebooks
- Audit or migrate SQL/CODE content across projects
- Manage permissions and access control across projects
- Automate bulk permission updates for users, groups, and collections
- Organize projects into collections by department, team, or topic
- Maintain user groups for simplified permission management
- Standardize workspace organization across your Hex instance
- Manage data connections and database integrations programmatically
- Automate connection setup for new workspaces or environments

For full notebook development and editing, use the Hex web UI directly.

Available Tools

Project Operations

- list_hex_projects: Lists available Hex projects - search_hex_projects: Search for Hex projects by pattern - get_hex_project: Get detailed information about a specific project

Project Execution

- run_hex_project: Execute a Hex project - get_hex_run_status: Check the status of a project run - get_hex_project_runs: Get the history of project runs - cancel_hex_run: Cancel a running project

Cell Operations (NEW)

- list_hex_cells: List all cells in a project with source code for SQL/CODE cells - update_hex_cell: Update SQL or CODE cell source and/or data connection

Permission Management (NEW)

- update_hex_project_user_sharing: Grant or revoke user access to projects - update_hex_project_group_sharing: Grant or revoke group access to projects - update_hex_project_collection_sharing: Add or remove projects from collections - update_hex_project_workspace_sharing: Update workspace-wide and public access

Collection Management (NEW)

- list_hex_collections: List all collections in the workspace - get_hex_collection: Get detailed information about a specific collection - create_hex_collection: Create a new collection with optional sharing settings - update_hex_collection: Update collection name, description, or sharing settings

Group Management (NEW)

- list_hex_groups: List all groups in the workspace - get_hex_group: Get detailed information about a specific group - create_hex_group: Create a new group with optional initial members - update_hex_group: Update group name and/or membership (add/remove users) - delete_hex_group: Delete a group from the workspace

Data Connection Management (NEW)

- list_hex_data_connections: List all data connections in the workspace - get_hex_data_connection: Get detailed information about a specific data connection - create_hex_data_connection: Create a new database/warehouse connection - update_hex_data_connection: Update connection configuration, credentials, or sharing

Installation

Using uv is the recommended way to install hex-mcp:

uv add hex-mcp

Or using pip:

pip install hex-mcp

To confirm it's working, you can run:

hex-mcp --version

Configuration

Using the config command (recommended)

The easiest way to configure hex-mcp is by using the config command and passing your API key and API URL (optional and defaults to https://app.hex.tech/api/v1):

hex-mcp config --api-key "your_hex_api_key" --api-url "https://app.hex.tech/api/v1"

> [!NOTE]
> This saves your configuration to a file in your home directory (e.g. ~/.hex-mcp/config.yml), making it available for all hex-mcp invocations.

Using environment variables

Alternatively, the Hex MCP server can be configured with environment variables:

- HEX_API_KEY: Your Hex API key
- HEX_API_URL: The Hex API base URL

When setting up environment variables for MCP servers they need to be either global for Cursor to pick them up or make use of uv's --env-file flag when invoking the server.

Using with Cursor

Cursor allows AI agents to interact with Hex via the MCP protocol. Follow these steps to set up and use hex-mcp with Cursor. You can create a .cursor/mcp.json file in your project root with the following content:

{
  "mcpServers": {
    "hex-mcp": {
      "command": "uv",
      "args": ["run", "hex-mcp", "run"]
    }
  }
}

Alternatively, you can use the hex-mcp command directly if it's in your PATH:

{
  "mcpServers": {
    "hex-mcp": {
      "command": "hex-mcp",
      "args": ["run"]
    }
  }
}

Once it's up and running, you can use it in Cursor by initiating a new AI (Agent) conversation and ask it to list or run a Hex project.

> [!IMPORTANT]
> The MCP server and CLI is still in development and subject to breaking changes.

Usage Examples

Reading Cell Content

Use list_hex_cells to read the structure and source code of a Hex notebook:

```python