Metadata-Version: 2.4
Name: hex-mcp
Version: 0.1.10
Summary: A MCP server for Hex
Author-email: Franccesco Orozco <franccesco@codingdose.info>
Requires-Python: >=3.12
Requires-Dist: backoff>=2.2.1
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp>=1.3.0
Requires-Dist: python-dotenv>=1.0.1
Requires-Dist: pyyaml>=6.0.2
Requires-Dist: typer>=0.15.2
Provides-Extra: dev
Requires-Dist: mcp[cli]>=1.3.0; extra == 'dev'
Description-Content-Type: text/markdown

# hex-mcp MCP server

A MCP server for Hex that implements the following tools:

- `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
- `get_hex_run_status`: Check the status of a project run
- `get_hex_project_runs`: Get the history of project runs
- `run_hex_project`: Execute a Hex project
- `cancel_hex_run`: Cancel a running project

## Installation

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

```bash
uv add hex-mcp
```

Or using pip:

```bash
pip install hex-mcp
```

To confirm it's working, you can run:

```bash
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`):

```bash
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:

```json
{
  "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:

```json
{
  "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.
