MCP十六进制服务器

一个模型上下文协议（MCP）服务器，提供与十六进制，现代分析平台。此服务器使Claude和其他AI助手能够与您的Hex项目交互、运行分析和管理您的数据工作流。

特性

项目管理

列出项目：浏览Hex工作区中所有可访问的项目
获取项目详细信息：检索有关特定项目的全面信息
创建预签名URL：生成可嵌入的URL以共享十六进制项目
高级搜索：按名称、描述、标签、作者、状态或日期筛选器查找项目
项目概要：通过运行历史和指标全面了解多个项目

项目执行

运行项目：使用自定义输入参数执行十六进制项目
监视器运行：检查项目执行的状态和进度
取消跑步：停止长时间运行或卡住的项目执行
运行历史：查看执行历史和过去的结果
批量操作：并行或按顺序运行多个项目进行批量分析
主动运行监控：实时监控所有正在执行和待执行的任务
项目调度：安排项目在特定时间运行或具有重复时间表

数据与分析

数据导出：以多种格式导出项目结果（CSV、JSON、Parquet、Excel）
执行分析：随着时间的推移，性能指标和趋势分析
工作空间分析：对所有项目和用户进行全面分析
性能监控：跟踪运行时趋势、成功率和使用模式

高级功能

费率限制处理：API限制的自动重试和错误处理
综合录井：调试友好的日志记录用于故障排除
类型安全：完全支持TypeScript，具有详细的类型定义
错误恢复：通过用户友好的消息进行强大的错误处理
批处理：通过可配置的并发性高效处理多个操作
智能过滤：具有多种条件组合的高级搜索功能

工具概述

此MCP服务器提供 14个综合工具 专为数据分析师和Hex高级用户设计：

项目管理（7个工具）：

hex_list_projects -使用分页浏览工作区项目
hex_get_project -获取详细的项目信息
hex_search_projects -高级搜索和过滤
hex_create_presigned_url -生成可嵌入的URL
hex_export_project_data -以多种格式导出结果
hex_bulk_run_projects -批量项目执行
hex_get_project_summary -多项目分析报告

项目执行（7个工具）：

hex_run_project -使用参数执行项目
hex_get_run_status -检查执行状态
hex_cancel_run -停止执行
hex_get_project_runs -查看跑步历史记录
hex_get_execution_analytics -绩效指标和趋势
hex_monitor_active_runs -实时运行监控
hex_schedule_project_run -安排重复执行

安装

来自NPM（推荐）

npx github:tomnagengast/mcp-server-hex

来源

git clone https://github.com/tomnagengast/mcp-server-hex.git
cd mcp-server-hex
npm install
npm run build
npm start

配置

环境变量

创建一个 .env 项目根目录中的文件：

# Required: Your Hex API token
HEX_API_TOKEN=your_hex_api_token_here

# Optional: Hex API base URL (defaults to https://app.hex.tech/api/v1)
HEX_API_BASE_URL=https://app.hex.tech/api/v1

# Optional: Request timeout in milliseconds (defaults to 30000)
HEX_REQUEST_TIMEOUT=30000

# Optional: Enable debug logging (defaults to false)
HEX_DEBUG=true

获取十六进制API令牌

登录到您的Hex工作区
首选设置 → API令牌
点击 创建令牌
从以下选项中选择：

- 个人访问令牌：有时间限制，与您的用户帐户绑定 - 工作区令牌：可以配置为永不过期，绑定到工作区

复制令牌并将其添加到您的 .env 文件

Claude桌面配置

将此添加到您的Claude Desktop配置文件中：

使用NPX（推荐）

{
  "mcpServers": {
    "hex": {
      "command": "npx",
      "args": ["github:tomnagengast/mcp-server-hex"],
      "env": {
        "HEX_API_TOKEN": "your_hex_api_token_here"
      }
    }
  }
}

使用本地安装

{
  "mcpServers": {
    "hex": {
      "command": "node",
      "args": ["path/to/mcp-server-hex/dist/index.js"],
      "env": {
        "HEX_API_TOKEN": "your_hex_api_token_here"
      }
    }
  }
}

可用工具

项目管理工具

`hex_list_projects`

列出Hex工作区中所有可见的项目。

参数：

limit （可选）：要返回的最大项目数（1-100，默认值：20）
after （可选）：分页光标显示下一页结果

`hex_get_project`

获取特定项目的详细信息。

参数：

project_id （必填）：项目的唯一标识符

`hex_create_presigned_url`

创建用于嵌入十六进制项目的预签名URL。

参数：

project_id （必填）：项目的唯一标识符
theme （可选）：嵌入式视图主题(light 或 dark，默认值： light)
hide_header （可选）：隐藏嵌入视图中的标题（默认值： false)
hide_controls （可选）：隐藏嵌入式视图中的控件（默认值： false)
fullscreen （可选）：全屏模式显示（默认： false)
input_params （可选）：输入要传递给项目的参数

`hex_search_projects`

按名称、描述、标签或作者搜索和筛选项目。

参数：

query （可选）：搜索查询以匹配项目名称、描述或标签
author （可选）：按作者姓名或电子邮件筛选
status （可选）：按项目状态筛选(DRAFT, PUBLISHED, ARCHIVED)
visibility （可选）：按项目可见性筛选(PUBLIC, PRIVATE, WORKSPACE)
tags （可选）：要筛选的标签数组（具有这些标签中任何一个的项目）
updated_after （可选）：在此日期之后更新的筛选项目（ISO 8601格式）
limit （可选）：要返回的最大项目数（1-100，默认值：20）

`hex_export_project_data`

生成导出URL或下载项目结果数据。

参数：

project_id （必填）：项目的唯一标识符
format （可选）：导出格式(csv, json, parquet, excel，默认值： csv)
include_metadata （可选）：在导出中包含项目元数据（默认值： true)
run_id （可选）：用于导出数据的特定运行ID（如果未提供，则使用最新的成功运行）

`hex_bulk_run_projects`

并行或按顺序运行多个项目进行批量分析。

参数：

project_configs （必填）：项目配置数组 project_id，可选 input_params，以及 use_cached_sql_results
execution_mode （可选）： parallel 或 sequential 执行（默认值： parallel)
max_concurrent （可选）：并行模式的最大并发运行数（1-10，默认值：5）
stop_on_error （可选）：如果任何项目在顺序模式下失败，则停止执行（默认值： false)

`hex_get_project_summary`

获取多个项目的全面摘要，包括状态、运行历史和指标。

参数：

project_ids （必填）：要汇总的项目ID数组
include_run_history （可选）：包括每个项目的最近运行历史记录（默认值： true)
include_performance_metrics （可选）：包括平均运行时间等性能指标（默认值： false)

项目执行工具

`hex_run_project`

触发Hex项目的执行。

参数：

project_id （必填）：项目的唯一标识符
input_params （可选）：输入要传递给项目的参数
update_published_results （可选）：更新已发布的应用程序结果缓存（默认值： false)
use_cached_sql_results （可选）：使用缓存的SQL查询结果（默认值： true)
notification_config （可选）：配置完成通知

`hex_get_run_status`

检查特定项目运行的状态。

参数：

project_id （必填）：项目的唯一标识符
run_id （必填）：跑步的唯一标识符

`hex_cancel_run`

取消正在进行的项目运行。

参数：

project_id （必填）：项目的唯一标识符
run_id （必填）：跑步的唯一标识符

`hex_get_project_runs`

获取特定项目的运行历史记录。

参数：

project_id （必填）：项目的唯一标识符
limit （可选）：要返回的最大运行次数（1-100，默认值：10）
status （可选）：按状态运行筛选器(PENDING, RUNNING, SUCCESS, ERROR, CANCELLED)

`hex_get_execution_analytics`

获取项目执行的分析和性能指标。

参数：

project_id （可选）：项目的唯一标识符（在工作区范围的分析中省略）
time_range （可选）：分析的时间范围(24h, 7d, 30d, 90d，默认值： 7d)
include_failed_runs （可选）：在分析中包含失败的运行（默认值： true)
group_by （可选）：如何对分析数据进行分组(day, week, month, project, user，默认值： day)

`hex_monitor_active_runs`

监控所有当前活动（正在运行或挂起）的项目执行。

参数：

include_pending （可选）：在监控中包括挂起的运行（默认值： true)
show_progress （可选）：显示可用的详细进度信息（默认值： false)
auto_refresh （可选）：指示这是否用于自动刷新监控（默认值： false)

`hex_schedule_project_run`

安排一个项目在特定时间运行或使用定期计划运行。

参数：

project_id （必填）：项目的唯一标识符
scheduled_time （必填）：何时运行（ISO 8601格式为“一次”，重复时间）
schedule_type （可选）：计划类型(once, daily, weekly, monthly，默认值： once)
input_params （可选）：输入要传递给项目的参数
timezone （可选）：计划执行的时区（默认值： UTC)
notification_config （可选）：计划运行的通知配置

使用示例

基本的项目管理

List all my Hex projects

高级项目搜索

Search for projects tagged with "sales" created by john@company.com

运行分析

Run the sales dashboard project with updated data for Q4 2024

批量操作

Run multiple quarterly reports in parallel with different parameters

监控执行情况

Check the status of the customer analysis run that started 10 minutes ago

执行分析

Show me execution analytics for the last 30 days grouped by project

主动运行监控

Monitor all currently running projects and show progress details

数据导出

Export the latest results from the revenue dashboard as CSV with metadata

项目调度

Schedule the daily report to run every morning at 9 AM EST

创建可共享链接

Create an embedded URL for the revenue dashboard with dark theme

综合项目分析

Get a detailed summary of projects A, B, and C including run history and performance metrics

费率限制和最佳实践

API费率限制：每分钟60个请求
并发内核：最多同时运行25次
项目运行：每分钟最多20个项目运行请求

最佳实践

尽可能使用缓存的SQL结果来提高性能
监控长期运行的项目，以避免资源浪费
对大型项目列表使用分页
为您的用例设置适当的超时

错误处理

服务器为常见场景提供全面的错误处理：

身份验证错误：清除无效API令牌的消息
速率限制：自动检测并提供重试建议
网络问题：具有可配置限制的超时处理
API错误：来自Hex API响应的用户友好错误消息

发展

先决条件

Node.js 18+
TypeScript 5+
具有API访问权限的十六进制工作空间

从源头构建

git clone https://github.com/tomnagengast/mcp-server-hex.git
cd mcp-server-hex
npm install
npm run build

在发展中奔跑

npm run dev

测试

npm test

代码检查

npm run lint
npm run typecheck

贡献

分叉存储库
创建要素分支(git checkout -b feature/amazing-feature)
提交您的更改(git commit -m 'Add amazing feature')
推到分支(git push origin feature/amazing-feature)
打开拉取请求

许可证

MIT许可证-请参阅许可证文件以获取详细信息。

支持

问题:
文档: API十六进制文档
MCP文件: 模型上下文协议

更新日志

v1.1.0版本

重大改进：增加了10个新的以分析师为中心的工具
项目搜索：按姓名、作者、标签、状态和日期进行高级筛选
数据导出：以CSV、JSON、Parquet和Excel格式导出项目结果
批量操作：并行和顺序执行多个项目
分析和监控：执行分析、性能指标和实时监控
项目调度：安排定期项目执行
增强文档：综合使用示例和工具参考
类型安全：改进了对所有新工具的TypeScript支持

v1.0.0

初始版本
完整的十六进制API集成
核心项目管理和执行工具（4个工具）
全面的错误处理和记录
TypeScript支持详细类型

MCP Server Hex

快速接入

详细介绍

MCP十六进制服务器

特性

项目管理

项目执行

数据与分析

高级功能

工具概述

安装

来自NPM（推荐）

来源

配置

环境变量

获取十六进制API令牌

Claude桌面配置

使用NPX（推荐）

使用本地安装

可用工具

项目管理工具

hex_list_projects

hex_get_project

hex_create_presigned_url

hex_search_projects

hex_export_project_data

hex_bulk_run_projects

hex_get_project_summary

项目执行工具

hex_run_project

hex_get_run_status

hex_cancel_run

hex_get_project_runs

hex_get_execution_analytics

hex_monitor_active_runs

hex_schedule_project_run

使用示例

基本的项目管理

高级项目搜索

运行分析

批量操作

监控执行情况

执行分析

主动运行监控

数据导出

项目调度

创建可共享链接

综合项目分析

费率限制和最佳实践

最佳实践

错误处理

发展

先决条件

从源头构建

在发展中奔跑

测试

代码检查

贡献

许可证

支持

更新日志

v1.1.0版本

v1.0.0

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP

`hex_list_projects`

`hex_get_project`

`hex_create_presigned_url`

`hex_search_projects`

`hex_export_project_data`

`hex_bulk_run_projects`

`hex_get_project_summary`

`hex_run_project`

`hex_get_run_status`

`hex_cancel_run`

`hex_get_project_runs`

`hex_get_execution_analytics`

`hex_monitor_active_runs`

`hex_schedule_project_run`