hex-mcp MCP server

hex-mcp MCP サーバー

オーケストレーション、モニタリング、セルのコンテンツへのアクセス、権限管理、コレクションの整理、グループ管理のツールを実装する、Hex 向けの MCP サーバーです。

このツールでできること（できないこと）

実用的なユースケース

オーケストレーションと自動化：

• 外部システム（Airflow DAG、CI/CD パイプライン）から Hex プロジェクトの実行を開始する
• プログラムから実行状況をモニタリングする
• 長時間実行されている実行や停止している実行をキャンセルする
• ワークスペース全体からプロジェクトを検索し、見つける

運用モニタリング：

• スケジュールされた実行が正常に完了したか確認する
• 監査用に実行履歴を取得する
• プロジェクトのメタデータ（所有者、最終編集日時、説明）にプログラムからアクセスする

セルのコンテンツへのアクセス（新機能）：

• ノートブックの構造とセルのメタデータを読み取る
• SQL セルから SQL クエリのソースコードを読み取る
• CODE セルから Python／R のコードを読み取る
• クエリの移行、コード分析、コンテンツ監査に役立ちます

権限管理（新機能）：

• プロジェクトへのユーザーおよびグループのアクセス権をプログラムから管理する
• 複数のプロジェクトの権限を一括更新する
• ワークスペース全体およびパブリックアクセスの設定を管理する
• コレクションに対してプロジェクトを追加または削除する

コレクションの整理（新機能）：

• プロジェクトを整理するためのコレクションを作成、管理する
• 部門、チーム、トピック別にプロジェクトを整理する
• コレクションの表示範囲とアクセス権を管理する
• プロジェクトを一括でコレクションに整理する

グループ管理（新機能）：

• 権限管理用のユーザーグループを作成、管理する
• 複数のユーザーを一括でグループに追加、またはグループから削除する
• グループを使用して、プロジェクト全体の権限管理を簡素化する
• チーム構成を整理された状態に保つ

データ接続管理（新機能）：

• データベースおよびデータウェアハウスの接続を一覧表示して管理する
• BigQuery、Snowflake、Postgres、Redshift、Athena、Databricks の接続を作成する
• 接続設定と認証情報を更新する
• ワークスペース内でのデータ接続の共有を管理する

重要な制限事項

ノートブックのコンテンツへのアクセスは限定的です：

• ✅ SQL セルと CODE セルのソースコンテンツを読み取れます
• ❌ MARKDOWN、INPUT、可視化セルは読み取れません
• ❌ セルを作成または削除できません
• ❌ ノートブックの構造を変更できません
• ❌ クエリ結果やグラフを表示できません
• ❌ ノートブックの依存関係やパラメーターを管理できません

次の用途には適していません：

• ノートブックをゼロから作成、執筆する
• ノートブックを共同で開発する
• クエリやコードの実行をデバッグする
• ノートブック全体をバックアップする（アクセスできるのは SQL／CODE セルのみです）
• Markdown ドキュメントや入力パラメーターを読み取る

使用するタイミング

次のような場合に hex-mcp を使用してください：

• 外部システムから Hex の実行をオーケストレーションする
• 実行状況と履歴をモニタリングする
• 既存のノートブックから SQL クエリとコードを読み取る
• プロジェクト全体の SQL／CODE コンテンツを監査または移行する
• プロジェクト全体の権限とアクセス制御を管理する
• ユーザー、グループ、コレクションの権限更新を一括で自動化する
• 部門、チーム、トピック別にプロジェクトをコレクションに整理する
• 権限管理を簡素化するためにユーザーグループを維持する
• Hex インスタンス全体でワークスペースの構成を標準化する
• データ接続とデータベース連携をプログラムから管理する
• 新しいワークスペースや環境の接続設定を自動化する

ノートブックの開発や編集をすべて行う場合は、Hex のウェブ UI を直接使用してください。

利用可能なツール

プロジェクト操作

• list_hex_projects：利用可能な Hex プロジェクトを一覧表示します
• search_hex_projects：パターンを指定して Hex プロジェクトを検索します
• get_hex_project：特定のプロジェクトの詳細情報を取得します

プロジェクトの実行

• run_hex_project：Hex プロジェクトを実行します
• get_hex_run_status：プロジェクト実行の状況を確認します
• get_hex_project_runs：プロジェクトの実行履歴を取得します
• cancel_hex_run：実行中のプロジェクトをキャンセルします

セル操作（新機能）

• list_hex_cells：プロジェクト内のすべてのセルを一覧表示し、SQL／CODE セルのソースコードを取得します
• update_hex_cell：SQL または CODE セルのソースおよび／またはデータ接続を更新します

権限管理（新機能）

• update_hex_project_user_sharing：プロジェクトへのユーザーアクセス権を付与または取り消します
• update_hex_project_group_sharing：プロジェクトへのグループアクセス権を付与または取り消します
• update_hex_project_collection_sharing：プロジェクトをコレクションに追加または削除します
• update_hex_project_workspace_sharing：ワークスペース全体および公開アクセスを更新します

コレクション管理（新機能）

• list_hex_collections：ワークスペース内のすべてのコレクションを一覧表示します
• get_hex_collection：特定のコレクションの詳細情報を取得します
• create_hex_collection：共有設定を任意で指定して、新しいコレクションを作成します
• update_hex_collection：コレクション名、説明、または共有設定を更新します

グループ管理（新機能）

• list_hex_groups：ワークスペース内のすべてのグループを一覧表示します
• get_hex_group：特定のグループの詳細情報を取得します
• create_hex_group：初期メンバーを任意で指定して、新しいグループを作成します
• update_hex_group：グループ名やメンバー構成（ユーザーの追加／削除）を更新します
• delete_hex_group：ワークスペースからグループを削除します

データ接続管理（新機能）

• list_hex_data_connections：ワークスペース内のすべてのデータ接続を一覧表示します
• get_hex_data_connection：特定のデータ接続の詳細情報を取得します
• create_hex_data_connection：新しいデータベース／ウェアハウス接続を作成します
• update_hex_data_connection：接続設定、認証情報、または共有設定を更新します

インストール

hex-mcp のインストールには uv の使用をおすすめします。

uv add hex-mcp

または、pip を使用します。

pip install hex-mcp

動作を確認するには、次のコマンドを実行します。

hex-mcp --version

設定

config コマンドを使用する（推奨）

hex-mcp を設定する最も簡単な方法は、config コマンドを使って API キーと API URL を渡すことです（API URL は省略可能で、省略した場合は https://app.hex.tech/api/v1 が使用されます）。

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

メモ

設定はホームディレクトリ内のファイル（例：~/.hex-mcp/config.yml）に保存され、すべての hex-mcp 呼び出しで使用できるようになります。

環境変数を使用する

また、環境変数を使用して Hex MCP サーバーを設定することもできます。

• HEX_API_KEY：Hex API キー
• HEX_API_URL：Hex API のベース URL

MCP サーバー用の環境変数を設定する場合、Cursor が読み込めるようにグローバルに設定するか、サーバーの起動時に uv の --env-file フラグを使用する必要があります。

Cursor での使用

Cursor を使うと、AI エージェントは MCP プロトコルを介して Hex とやり取りできます。次の手順に従って、hex-mcp を Cursor に設定して使用してください。プロジェクトのルートに .cursor/mcp.json ファイルを作成し、次の内容を記述します。

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

または、hex-mcp コマンドが PATH に含まれている場合は、コマンドを直接使用できます。

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

起動したら、Cursor で新しい AI（エージェント）との会話を開始し、Hex プロジェクトの一覧表示または実行を依頼できます。

重要

MCP サーバーと CLI は現在も開発中であり、互換性を損なう変更が行われる可能性があります。

使用例

セルの内容を読み取る

list_hex_cells を使って、Hex ノートブックの構造とソースコードを読み取ります。

# List all cells in a project
cells = list_hex_cells(project_id="your-project-uuid")

# The response includes cell metadata and source code for SQL/CODE cells
# Example response structure:
{
    "values": [
        {
            "id": "cell-uuid-123",
            "staticId": "static-id-456",
            "cellType": "SQL",
            "label": "Load Customer Data",
            "dataConnectionId": "connection-uuid-789",
            "contents": {
                "sqlCell": {
                    "source": "SELECT * FROM customers WHERE active = true"
                },
                "codeCell": null
            }
        },
        {
            "id": "cell-uuid-456",
            "cellType": "CODE",
            "label": "Process Data",
            "dataConnectionId": null,
            "contents": {
                "sqlCell": null,
                "codeCell": {
                    "source": "import pandas as pd\ndf = df.dropna()"
                }
            }
        },
        {
            "id": "cell-uuid-789",
            "cellType": "MARKDOWN",
            "label": "Documentation",
            "dataConnectionId": null,
            "contents": {
                "sqlCell": null,
                "codeCell": null
            }
        }
    ],
    "pagination": {
        "next": null,
        "previous": null
    }
}

注意：ソース内容が含まれるのは SQL セルと CODE セルのみです。MARKDOWN、INPUT、可視化の各セルでは、sqlCell と codeCell の両方が null を返します。

ページネーション

セル数の多いプロジェクトでは、ページネーションを使用します。

# First page
page1 = list_hex_cells(project_id="your-project-uuid", limit=50)

# Next page using cursor
if page1["pagination"]["next"]:
    page2 = list_hex_cells(
        project_id="your-project-uuid",
        limit=50,
        after=page1["pagination"]["next"]
    )

# Previous page
if page2["pagination"]["previous"]:
    page1_again = list_hex_cells(
        project_id="your-project-uuid",
        limit=50,
        before=page2["pagination"]["previous"]
    )

セルの内容を更新する

SQL セルまたは CODE セルをプログラムで更新します。

# Update SQL cell source code
result = update_hex_cell(
    cell_id="cell-uuid-123",
    sql_source="SELECT * FROM updated_table WHERE active = true"
)

# Update CODE cell source code
result = update_hex_cell(
    cell_id="cell-uuid-456",
    code_source="import pandas as pd\ndf = df.dropna()"
)

# Update SQL cell data connection (without changing source)
result = update_hex_cell(
    cell_id="cell-uuid-123",
    data_connection_id="new-connection-uuid"
)

# Update both SQL source and connection in one call
result = update_hex_cell(
    cell_id="cell-uuid-123",
    sql_source="SELECT * FROM production.customers",
    data_connection_id="production-connection-uuid"
)

重要：

• 更新できるのは SQL および CODE のセルタイプのみです
• MARKDOWN、INPUT、可視化の各セルは更新できません
• EDIT_PROJECT_CONTENTS 権限が必要です
• 同じ呼び出しで sql_source と code_source の両方を更新することはできません（セルは SQL または CODE のいずれかです）

クエリ移行の例

プロジェクト間で SQL クエリを抽出して更新します。

import json

# Get all cells from source project
cells_response = list_hex_cells(project_id="source-project-uuid")
cells = json.loads(cells_response)

# Filter for SQL cells
sql_cells = [
    cell for cell in cells["values"]
    if cell["cellType"] == "SQL" and cell["contents"]["sqlCell"]
]

# Migrate queries to new data connection
new_connection_id = "production-bigquery-connection"

for cell in sql_cells:
    original_query = cell["contents"]["sqlCell"]["source"]

    # Update table references (example: dev -> prod)
    updated_query = original_query.replace("dev.schema", "prod.schema")

    # Update the cell with new query and connection
    result = update_hex_cell(
        cell_id=cell["id"],
        sql_source=updated_query,
        data_connection_id=new_connection_id
    )

    print(f"Updated cell: {cell['label']}")

print(f"Migrated {len(sql_cells)} SQL cells to production")

コードリファクタリングの例

複数のセルに含まれる Python コードを一括更新します。

import json

# Get all CODE cells
cells_response = list_hex_cells(project_id="project-uuid")
cells = json.loads(cells_response)

code_cells = [
    cell for cell in cells["values"]
    if cell["cellType"] == "CODE" and cell["contents"]["codeCell"]
]

# Update import statements
for cell in code_cells:
    original_code = cell["contents"]["codeCell"]["source"]

    # Replace deprecated import
    if "from old_library" in original_code:
        updated_code = original_code.replace(
            "from old_library import func",
            "from new_library import func"
        )

        # Update the cell
        result = update_hex_cell(
            cell_id=cell["id"],
            code_source=updated_code
        )

        print(f"Updated cell: {cell['label']}")

プロジェクトの権限管理

共有エンドポイントを使用して、Hex プロジェクトへのアクセスをプログラムで制御します。

ユーザーアクセスの付与

from hex_mcp.server import update_hex_project_user_sharing

# Grant edit access to a single user
result = update_hex_project_user_sharing(
    project_id="project-123",
    user_permissions=[
        {"user_id": "user-456", "access": "CAN_EDIT"}
    ]
)

# Grant access to multiple users with different permissions
result = update_hex_project_user_sharing(
    project_id="project-123",
    user_permissions=[
        {"user_id": "user-001", "access": "CAN_VIEW"},
        {"user_id": "user-002", "access": "CAN_EDIT"},
        {"user_id": "user-003", "access": "FULL_ACCESS"}
    ]
)

# Revoke user access
result = update_hex_project_user_sharing(
    project_id="project-123",
    user_permissions=[
        {"user_id": "user-456", "access": "NONE"}
    ]
)

アクセスレベル：

• NONE：すべてのアクセスを取り消します
• APP_ONLY：アプリ内でのみアクセスできます（公開済みバージョン）
• CAN_VIEW：ロジックビューでプロジェクトを閲覧できます（読み取り専用）
• CAN_EDIT：プロジェクトの内容を編集できます
• FULL_ACCESS：内容の編集とプロジェクト設定／権限の管理ができます

グループアクセスの付与

from hex_mcp.server import update_hex_project_group_sharing

# Grant access to a group
result = update_hex_project_group_sharing(
    project_id="project-123",
    group_permissions=[
        {"group_id": "group-789", "access": "CAN_VIEW"}
    ]
)

# Grant access to multiple groups
result = update_hex_project_group_sharing(
    project_id="project-123",
    group_permissions=[
        {"group_id": "analytics-team", "access": "CAN_EDIT"},
        {"group_id": "leadership-team", "access": "CAN_VIEW"}
    ]
)

コレクションへのプロジェクトの追加

from hex_mcp.server import update_hex_project_collection_sharing

# Add project to a collection
result = update_hex_project_collection_sharing(
    project_id="project-123",
    collection_permissions=[
        {"collection_id": "collection-456", "access": "CAN_VIEW"}
    ]
)

# Add to multiple collections with different access levels
result = update_hex_project_collection_sharing(
    project_id="project-123",
    collection_permissions=[
        {"collection_id": "public-dashboards", "access": "APP_ONLY"},
        {"collection_id": "internal-analytics", "access": "CAN_EDIT"}
    ]
)

# Remove from collection
result = update_hex_project_collection_sharing(
    project_id="project-123",
    collection_permissions=[
        {"collection_id": "collection-456", "access": "NONE"}
    ]
)

ワークスペースと公開アクセスの管理

from hex_mcp.server import update_hex_project_workspace_sharing

# Make project viewable by entire workspace
result = update_hex_project_workspace_sharing(
    project_id="project-123",
    workspace_access="CAN_VIEW"
)

# Make project publicly accessible
result = update_hex_project_workspace_sharing(
    project_id="project-123",
    public_access="APP_ONLY"
)

# Update both workspace and public access
result = update_hex_project_workspace_sharing(
    project_id="project-123",
    workspace_access="CAN_EDIT",
    public_access="APP_ONLY"
)

# Revoke public access (keep workspace access)
result = update_hex_project_workspace_sharing(
    project_id="project-123",
    public_access="NONE"
)

一括権限管理の例

複数のプロジェクトで権限を標準化します。

import json
from hex_mcp.server import (
    list_hex_projects,
    update_hex_project_user_sharing,
    update_hex_project_workspace_sharing
)

# Get all projects
projects_response = list_hex_projects()
projects = json.loads(projects_response)

# Define standard access policies
analytics_team_users = ["user-001", "user-002", "user-003"]
leadership_users = ["user-100", "user-101"]

for project in projects:
    project_id = project["projectId"]

    # Grant analytics team edit access
    update_hex_project_user_sharing(
        project_id=project_id,
        user_permissions=[
            {"user_id": user_id, "access": "CAN_EDIT"}
            for user_id in analytics_team_users
        ]
    )

    # Grant leadership view access
    update_hex_project_user_sharing(
        project_id=project_id,
        user_permissions=[
            {"user_id": user_id, "access": "CAN_VIEW"}
            for user_id in leadership_users
        ]
    )

    # Make viewable by workspace, not public
    update_hex_project_workspace_sharing(
        project_id=project_id,
        workspace_access="CAN_VIEW",
        public_access="NONE"
    )

    print(f"Updated permissions for: {project['name']}")

重要な注意事項：

• すべての共有操作には、適切なワークスペース権限が必要です
• ユーザー ID／グループ ID は、Hex ワークスペースに存在している必要があります
• コレクション ID は有効であり、アクセス権があるコレクションのものである必要があります
• ワークスペースアクセスは、すべてのワークスペースメンバーに適用されます
• 公開アクセス（publicWeb）を許可すると、リンクを知っている人なら誰でもアクセスできます

コレクションの管理

ワークスペースをより整理しやすくするために、プロジェクトをコレクションに整理します。

コレクションの一覧表示

from hex_mcp.server import list_hex_collections
import json

# List all collections
collections = list_hex_collections()
data = json.loads(collections)

for collection in data["values"]:
    print(f"{collection['name']}: {collection['id']}")
    print(f"  Created by: {collection.get('creator', {}).get('email', 'N/A')}")

# List with pagination
page1 = list_hex_collections(limit=10)
data = json.loads(page1)

if data["pagination"]["next"]:
    page2 = list_hex_collections(limit=10, after=data["pagination"]["next"])

コレクションの詳細の取得

from hex_mcp.server import get_hex_collection
import json

# Get specific collection
collection = get_hex_collection(collection_id="collection-123")
data = json.loads(collection)

print(f"Collection: {data['name']}")
print(f"Description: {data.get('description', 'No description')}")
print(f"Sharing with {len(data['sharing'].get('users', []))} users")
print(f"Sharing with {len(data['sharing'].get('groups', []))} groups")

コレクションの作成

from hex_mcp.server import create_hex_collection
import json

# Create simple collection
collection = create_hex_collection(
    name="Q4 2026 Analytics",
    description="Analytics projects for Q4 2026"
)
data = json.loads(collection)
print(f"Created collection: {data['id']}")

# Create with sharing settings
collection = create_hex_collection(
    name="Executive Dashboards",
    description="Dashboards for executive team",
    sharing_users=[
        {"id": "user-ceo", "access": "CAN_VIEW"},
        {"id": "user-cfo", "access": "CAN_VIEW"}
    ],
    workspace_access="NONE"  # Only specified users can access
)

# Create with group access
collection = create_hex_collection(
    name="Finance Reports",
    description="Financial reporting and analysis",
    sharing_groups=[
        {"id": "finance-team", "access": "CAN_EDIT"}
    ],
    workspace_access="CAN_VIEW"
)

コレクションの更新

from hex_mcp.server import update_hex_collection
import json

# Update collection name and description
result = update_hex_collection(
    collection_id="collection-123",
    name="Q1 2027 Analytics",
    description="Updated for Q1 2027"
)

# Update sharing settings
result = update_hex_collection(
    collection_id="collection-123",
    sharing_users=[
        {"id": "user-456", "access": "CAN_EDIT"}
    ],
    workspace_access="CAN_VIEW"
)

# Update multiple fields at once
result = update_hex_collection(
    collection_id="collection-123",
    name="Updated Collection Name",
    description="Updated description",
    sharing_groups=[
        {"id": "analytics-team", "access": "CAN_EDIT"}
    ],
    workspace_access="CAN_VIEW"
)

コレクション整理の例

すべてのプロジェクトを部門ごとに整理します。

import json
from hex_mcp.server import (
    list_hex_projects,
    list_hex_collections,
    create_hex_collection,
    update_hex_project_collection_sharing
)

# Define department structure
departments = {
    "Engineering": ["user-eng-lead", "group-engineering"],
    "Finance": ["user-fin-lead", "group-finance"],
    "Marketing": ["user-mkt-lead", "group-marketing"]
}

# Create collections for each department
collection_ids = {}
for dept_name, members in departments.items():
    # Create collection
    collection = create_hex_collection(
        name=f"{dept_name} Projects",
        description=f"All {dept_name} department projects",
        workspace_access="CAN_VIEW"
    )
    data = json.loads(collection)
    collection_ids[dept_name] = data["id"]
    print(f"Created collection for {dept_name}: {data['id']}")

# Get all projects
projects = list_hex_projects()
projects_data = json.loads(projects)

# Organize projects into collections based on name patterns
for project in projects_data:
    project_id = project["projectId"]
    project_name = project["name"].lower()

    # Determine which collection(s) this project belongs to
    if "engineering" in project_name or "technical" in project_name:
        update_hex_project_collection_sharing(
            project_id=project_id,
            collection_permissions=[
                {"collection_id": collection_ids["Engineering"], "access": "CAN_EDIT"}
            ]
        )
        print(f"Added '{project['name']}' to Engineering collection")

    elif "finance" in project_name or "revenue" in project_name:
        update_hex_project_collection_sharing(
            project_id=project_id,
            collection_permissions=[
                {"collection_id": collection_ids["Finance"], "access": "CAN_EDIT"}
            ]
        )
        print(f"Added '{project['name']}' to Finance collection")

    elif "marketing" in project_name or "campaign" in project_name:
        update_hex_project_collection_sharing(
            project_id=project_id,
            collection_permissions=[
                {"collection_id": collection_ids["Marketing"], "access": "CAN_EDIT"}
            ]
        )
        print(f"Added '{project['name']}' to Marketing collection")

print("Collection organization complete!")

コレクション管理に関する注意事項：

• コレクションを使用すると、チーム、部門、トピックごとにプロジェクトを整理できます
• コレクションには、プロジェクトとは独立した共有設定を指定できます
• 1 つのプロジェクトを複数のコレクションに所属させることができます
• コレクションに対するワークスペースアクセスは、誰がそのコレクションの存在を確認できるかを制御します
• コレクションの作成には、適切なワークスペース権限が必要です

グループの管理

ユーザーをグループにまとめ、権限管理を簡素化します。

グループの一覧表示

from hex_mcp.server import list_hex_groups
import json

# List all groups
groups = list_hex_groups()
data = json.loads(groups)

for group in data["values"]:
    print(f"{group['name']}: {group['id']}")
    print(f"  Created: {group['createdAt']}")

# List with pagination and sorting
page1 = list_hex_groups(
    limit=10,
    sort_by="name",
    sort_direction="asc"
)
data = json.loads(page1)

if data["pagination"]["next"]:
    page2 = list_hex_groups(limit=10, after=data["pagination"]["next"])

グループの詳細の取得

from hex_mcp.server import get_hex_group
import json

# Get specific group
group = get_hex_group(group_id="group-123")
data = json.loads(group)

print(f"Group: {data['name']}")
print(f"ID: {data['id']}")
print(f"Created: {data['createdAt']}")

グループの作成

from hex_mcp.server import create_hex_group
import json

# Create simple group
group = create_hex_group(name="Analytics Team")
data = json.loads(group)
print(f"Created group: {data['id']}")

# Create with initial members
group = create_hex_group(
    name="Finance Team",
    member_user_ids=[
        "user-123",
        "user-456",
        "user-789"
    ]
)
data = json.loads(group)
print(f"Created group with 3 members: {data['id']}")

グループの更新

from hex_mcp.server import update_hex_group
import json

# Update group name
result = update_hex_group(
    group_id="group-123",
    name="Senior Analytics Team"
)

# Add members to group
result = update_hex_group(
    group_id="group-123",
    add_member_user_ids=["user-new-1", "user-new-2"]
)

# Remove members from group
result = update_hex_group(
    group_id="group-123",
    remove_member_user_ids=["user-old-1"]
)

# Update name and membership together
result = update_hex_group(
    group_id="group-123",
    name="Lead Analytics Team",
    add_member_user_ids=["user-lead"],
    remove_member_user_ids=["user-junior"]
)

グループの削除

from hex_mcp.server import delete_hex_group

# Delete a group (does not delete the users, only the group)
result = delete_hex_group(group_id="group-old-team")
print(result)  # "Group deleted successfully"

グループ一括管理の例

部門ごとのグループを作成し、ユーザーを割り当てます。

import json
from hex_mcp.server import (
    create_hex_group,
    update_hex_group,
    update_hex_project_group_sharing
)

# Define department structure with user lists
departments = {
    "Engineering": {
        "leads": ["user-eng-lead-1", "user-eng-lead-2"],
        "members": ["user-eng-1", "user-eng-2", "user-eng-3"]
    },
    "Data Science": {
        "leads": ["user-ds-lead"],
        "members": ["user-ds-1", "user-ds-2", "user-ds-3", "user-ds-4"]
    },
    "Analytics": {
        "leads": ["user-analytics-lead"],
        "members": ["user-analyst-1", "user-analyst-2"]
    }
}

# Create groups for each department
group_ids = {}
for dept_name, users in departments.items():
    # Create main department group
    all_members = users["leads"] + users["members"]
    group = create_hex_group(
        name=f"{dept_name} Team",
        member_user_ids=all_members
    )
    data = json.loads(group)
    group_ids[dept_name] = data["id"]
    print(f"Created {dept_name} Team: {data['id']} ({len(all_members)} members)")

    # Create leadership sub-group
    lead_group = create_hex_group(
        name=f"{dept_name} Leadership",
        member_user_ids=users["leads"]
    )
    lead_data = json.loads(lead_group)
    group_ids[f"{dept_name}_Leadership"] = lead_data["id"]
    print(f"Created {dept_name} Leadership: {lead_data['id']} ({len(users['leads'])} members)")

# Grant group access to relevant projects
# Engineering team gets edit access to technical projects
update_hex_project_group_sharing(
    project_id="technical-project-123",
    group_permissions=[
        {"group_id": group_ids["Engineering"], "access": "CAN_EDIT"}
    ]
)

# Analytics team gets view access to all dashboards
update_hex_project_group_sharing(
    project_id="dashboard-project-456",
    group_permissions=[
        {"group_id": group_ids["Analytics"], "access": "CAN_VIEW"}
    ]
)

# Leadership groups get view access to executive dashboards
for dept in ["Engineering", "Data Science", "Analytics"]:
    leadership_group_id = group_ids[f"{dept}_Leadership"]
    update_hex_project_group_sharing(
        project_id="executive-dashboard-789",
        group_permissions=[
            {"group_id": leadership_group_id, "access": "CAN_VIEW"}
        ]
    )

print("Group-based permission management complete!")

チーム再編の例

グループのメンバーシップを更新して、チームの変更に対応します。

import json
from hex_mcp.server import (
    list_hex_groups,
    update_hex_group
)

# Get all groups
groups = list_hex_groups()
groups_data = json.loads(groups)

# Find specific groups that need updates
engineering_group = None
for group in groups_data["values"]:
    if group["name"] == "Engineering Team":
        engineering_group = group
        break

if engineering_group:
    # New hires joining
    new_engineers = ["user-new-eng-1", "user-new-eng-2"]

    # Engineers leaving
    departing_engineers = ["user-old-eng-1"]

    # Update group membership
    result = update_hex_group(
        group_id=engineering_group["id"],
        add_member_user_ids=new_engineers,
        remove_member_user_ids=departing_engineers
    )

    print(f"Updated {engineering_group['name']}")
    print(f"  Added: {len(new_engineers)} members")
    print(f"  Removed: {len(departing_engineers)} members")

グループ管理に関する注意事項：

• グループを使用すると、複数のユーザーに一度にアクセス権を付与できるため、権限管理を簡素化できます
• 1 人のユーザーが複数のグループに所属できます
• 1 回の更新操作で追加または削除できるユーザーは最大 100 人です
• グループを削除してもユーザーは削除されず、グループ自体のみが削除されます
• グループの権限は、すべてのグループメンバーに継承されます
• プロジェクト共有エンドポイントとグループを併用して、チーム全体にアクセス権を付与します

データ接続の管理

Hex プロジェクトのデータベース接続とウェアハウス接続を管理します。

データ接続の一覧表示

from hex_mcp.server import list_hex_data_connections
import json

# List all data connections
connections = list_hex_data_connections()
data = json.loads(connections)

for conn in data["values"]:
    print(f"{conn['name']} ({conn['type']}): {conn['id']}")
    if conn.get('description'):
        print(f"  Description: {conn['description']}")

# List with pagination and sorting
page1 = list_hex_data_connections(
    limit=10,
    sort_by="NAME",
    sort_direction="asc"
)
data = json.loads(page1)

if data["pagination"]["next"]:
    page2 = list_hex_data_connections(limit=10, after=data["pagination"]["next"])

データ接続の詳細の取得

from hex_mcp.server import get_hex_data_connection
import json

# Get specific connection
connection = get_hex_data_connection(connection_id="conn-123")
data = json.loads(connection)

print(f"Connection: {data['name']}")
print(f"Type: {data['type']}")
print(f"Description: {data.get('description', 'N/A')}")
print(f"Include Magic: {data.get('includeMagic', False)}")
print(f"Allow Writeback: {data.get('allowWritebackCells', False)}")

# Check sharing settings
if 'sharing' in data:
    workspace = data['sharing'].get('workspace', {})
    print(f"Workspace Access: {workspace.get('members', 'None')}")

データ接続の作成

from hex_mcp.server import create_hex_data_connection
import json

# Create BigQuery connection
bigquery_conn = create_hex_data_connection(
    name="Production BigQuery",
    connection_type="bigquery",
    connection_details={
        "bigquery": {
            "serviceAccountJsonConfig": json.dumps(service_account_config),
            "projectId": "my-gcp-project",
            "enableStorageApi": True,
            "enableDriveAccess": False
        }
    },
    description="Production data warehouse for analytics",
    include_magic=True,
    allow_writeback_cells=False,
    sharing={
        "workspace": {
            "members": "CAN_USE"
        }
    }
)
data = json.loads(bigquery_conn)
print(f"Created BigQuery connection: {data['id']}")

# Create Snowflake connection
snowflake_conn = create_hex_data_connection(
    name="Snowflake Analytics",
    connection_type="snowflake",
    connection_details={
        "snowflake": {
            "account": "my-account",
            "warehouse": "ANALYTICS_WH",
            "database": "ANALYTICS_DB",
            "schema": "PUBLIC",
            "username": "hex_service",
            "password": "secure_password"
        }
    },
    description="Snowflake warehouse for analytics",
    include_magic=True
)
data = json.loads(snowflake_conn)
print(f"Created Snowflake connection: {data['id']}")

# Create Postgres connection
postgres_conn = create_hex_data_connection(
    name="Application Database",
    connection_type="postgres",
    connection_details={
        "postgres": {
            "hostname": "db.example.com",
            "port": 5432,
            "database": "app_db",
            "username": "readonly_user",
            "password": "secure_password",
            "ssl": True
        }
    },
    description="Production application database (read-only)",
    connect_via_ssh=False,
    include_magic=True,
    allow_writeback_cells=False
)
data = json.loads(postgres_conn)
print(f"Created Postgres connection: {data['id']}")

データ接続の更新

from hex_mcp.server import update_hex_data_connection
import json

# Update connection name and description
result = update_hex_data_connection(
    connection_id="conn-123",
    name="Updated Production BigQuery",
    description="Updated production data warehouse for analytics and reporting"
)
data = json.loads(result)
print(f"Updated connection: {data['name']}")

# Update connection settings
result = update_hex_data_connection(
    connection_id="conn-123",
    include_magic=False,
    allow_writeback_cells=True
)
print("Updated connection settings")

# Update connection sharing
result = update_hex_data_connection(
    connection_id="conn-123",
    sharing={
        "workspace": {
            "members": "CAN_USE",
            "guests": "NONE"
        },
        "groups": {
            "upsert": [
                {"group": {"id": "analytics-team-group-id"}, "access": "CAN_USE"},
                {"group": {"id": "data-eng-group-id"}, "access": "CAN_ADMIN"}
            ]
        }
    }
)
print("Updated connection sharing")

# Rotate credentials by updating connection details
result = update_hex_data_connection(
    connection_id="conn-123",
    connection_details={
        "bigquery": {
            "serviceAccountJsonConfig": json.dumps(new_service_account),
            "projectId": "my-gcp-project",
            "enableStorageApi": True,
            "enableDriveAccess": False
        }
    }
)
print("Rotated connection credentials")

接続の一括設定

新しいワークスペースや環境向けの接続設定を自動化します。

from hex_mcp.server import create_hex_data_connection
import json

# Define standard connections for a workspace
connection_configs = {
    "Production BigQuery": {
        "type": "bigquery",
        "details": {
            "bigquery": {
                "serviceAccountJsonConfig": json.dumps(prod_bq_creds),
                "projectId": "prod-project",
                "enableStorageApi": True
            }
        },
        "description": "Production BigQuery warehouse"
    },
    "Staging BigQuery": {
        "type": "bigquery",
        "details": {
            "bigquery": {
                "serviceAccountJsonConfig": json.dumps(staging_bq_creds),
                "projectId": "staging-project",
                "enableStorageApi": True
            }
        },
        "description": "Staging BigQuery warehouse"
    },
    "Production Snowflake": {
        "type": "snowflake",
        "details": {
            "snowflake": {
                "account": "prod-account",
                "warehouse": "PROD_WH",
                "database": "PROD_DB",
                "username": "hex_prod",
                "password": prod_sf_password
            }
        },
        "description": "Production Snowflake warehouse"
    },
    "Application DB": {
        "type": "postgres",
        "details": {
            "postgres": {
                "hostname": "prod-db.example.com",
                "port": 5432,
                "database": "app_db",
                "username": "readonly",
                "password": postgres_password,
                "ssl": True
            }
        },
        "description": "Application database (read-only)"
    }
}

# Create all connections
created_connections = {}
for name, config in connection_configs.items():
    connection = create_hex_data_connection(
        name=name,
        connection_type=config["type"],
        connection_details=config["details"],
        description=config["description"],
        include_magic=True,
        allow_writeback_cells=False,
        sharing={
            "workspace": {
                "members": "CAN_USE"
            }
        }
    )
    data = json.loads(connection)
    created_connections[name] = data["id"]
    print(f"Created {name}: {data['id']}")

print(f"\nCreated {len(created_connections)} data connections")

データ接続管理に関する注意事項：

• サポート対象の接続タイプ：BigQuery、Snowflake、Postgres、Redshift、Athena、Databricks
• 各接続タイプには、connection_details に固有の設定要件があります
• 接続の認証情報は Hex によって安全に保管されます
• 共有設定を使用して、各接続を利用できるユーザーを制御します
• CAN_USE アクセスではデータのクエリが可能になり、CAN_ADMIN アクセスでは設定を変更できます
• セキュアな接続のため、connect_via_ssh パラメーターによる SSH トンネリングがサポートされています
• 機密性の高いデータソースには、接続レベルのアクセス制御の使用を検討してください

このフォークについて

このフォークは、上流の hex-mcp パッケージをバグ修正と新しいセル操作機能で拡張したものです。

バグ修正（上流 v0.1.10）

• 5 つのツールで戻り値の型が -> str と宣言されていましたが、Python の辞書やリストを返していました
• これにより、Claude Code MCP 統合で pydantic の検証エラーが発生していました
• src/hex_mcp/server.py の return 文に json.dumps() を追加して修正しました

修正したツール（74、172、187、206、229 行目）：

• list_hex_projects()
• get_hex_project()
• get_hex_run_status()
• get_hex_project_runs()
• run_hex_project()

新機能

セル操作（Hex API 完全実装のフェーズ 1）：

• list_hex_cells() - ノートブックの構造とセルのソースコード（SQL/CODE セル）を読み取ります
• update_hex_cell() - SQL/CODE セルのソースコードとデータ接続を更新します
• 29 件のテストに合格した包括的なテストスイート（すべてモックを使用し、認証情報は不要です）
• クエリ移行とコードのリファクタリングに関する使用例を含む、完全なドキュメント

権限管理（Hex API 完全実装のフェーズ 2）：

• update_hex_project_user_sharing() - プロジェクトへのユーザーアクセスを許可または取り消します
• update_hex_project_group_sharing() - プロジェクトへのグループアクセスを許可または取り消します
• update_hex_project_collection_sharing() - コレクションへのプロジェクトの追加または削除を行います
• update_hex_project_workspace_sharing() - ワークスペース全体およびパブリックアクセスを管理します
• すべての共有シナリオを対象とした、追加の 18 件のテストに合格しました
• 一括権限管理の完全な使用例

コレクション管理（Hex API 完全実装のフェーズ 3）：

• list_hex_collections() - ワークスペース内のすべてのコレクションを一覧表示します
• get_hex_collection() - 共有設定を含むコレクションの詳細を取得します
• create_hex_collection() - 共有設定を任意で指定してコレクションを作成します
• update_hex_collection() - コレクションのメタデータと共有設定を更新します
• コレクションの CRUD 操作を対象とした、追加の 18 件のテストに合格しました
• 部門ごとにワークスペースを整理するための完全な使用例

グループ管理（Hex API 完全実装のフェーズ 4）：

• list_hex_groups() - ワークスペース内のすべてのグループを一覧表示します
• get_hex_group() - グループの詳細を取得します
• create_hex_group() - 初期メンバーを任意で指定してグループを作成します
• update_hex_group() - グループ名とメンバー構成を更新します（最大 100 人のユーザーを追加または削除できます）
• delete_hex_group() - ワークスペースからグループを削除します
• グループの CRUD 操作全体を対象とした、追加の 21 件のテストに合格しました
• 部門ベースのグループ管理とチーム再編成に関する完全な使用例
• すべての関数に、包括的な Google スタイルの docstring が含まれています

データ接続管理（Hex API 完全実装のフェーズ 5）：

• list_hex_data_connections() - ページネーションと並べ替えに対応して、すべてのデータ接続を一覧表示します
• get_hex_data_connection() - 認証情報と共有設定を含む接続の詳細を取得します
• create_hex_data_connection() - BigQuery、Snowflake、Postgres、Redshift、Athena、Databricks の接続を作成します
• update_hex_data_connection() - 接続設定、認証情報、共有設定を更新します
• データ接続の CRUD 操作を対象とした、追加の 18 件のテストに合格しました
• 接続の設定、認証情報のローテーション、一括デプロイに関する完全な使用例
• 主要な 6 種類すべてのデータベース／データウェアハウス接続に対応しています
• 接続タイプの仕様を詳しく記載した、完全な Google スタイルの docstring

テストインフラストラクチャ：

• モック認証を使用した包括的なテストフィクスチャ
• 105 件のテストに合格、スキップは 0 件（すべてモックを使用し、認証情報は不要です）
• 各フェーズでテストカバレッジを拡大
• テストで本番環境の認証情報が使用されないようにするセキュリティチェック
• pytest、pytest-asyncio、pytest-cov との統合
• 本番環境とテスト環境の両方で動作するよう、バックオフハンドラーを修正

ドキュメント：

• OpenAPI 仕様の完全な分析（OPENAPI-VALIDATION.md を参照）
• 詳細な実装計画（IMPLEMENTATION-PLAN.md を参照）
• テスト戦略ガイド（TEST-STRATEGY.md を参照）
• すべての新機能の使用例

アップストリーム：https://github.com/franccesco/hex-mcp

ステータス：ブランチ bugfix/fast-mcp-return-types には、バグ修正と新しいセル操作機能の両方が含まれています。希望する場合は、アップストリームへの PR を提出できる状態です。