AI导哈

Hex MCP 服务器

Hex MCP 服务器是一个模型上下文协议服务器，为大型语言模型提供访问 Hex API 的能力，使 AI 助手能够与 Hex 项目交互、运行分析和管理数据工作流。

  • by oliviac12
  • JavaScript
  • 本地部署
  • 更新于
在 GitHub 查看 oliviac12/hex-mcp-server

使用说明

十六进制MCP服务器

MCP（模型上下文协议）服务器，为LLM提供访问Hex API的权限，使人工智能助手能够与Hex项目交互、运行分析和管理数据工作流。

特性

  • 项目管理：列出并检索十六进制项目
  • 项目执行：使用自定义输入运行项目并监控执行状态
  • 嵌入式生成：为Hex项目创建可自定义的嵌入URL
  • 速率限制监控：跟踪API使用情况以保持在限制范围内

安装

通过NPX（推荐）

npx @olivia/hex-mcp-server

本地安装

npm install @olivia/hex-mcp-server

先决条件

  1. 十六进制API令牌：您需要一个十六进制API令牌。您可以从以下位置创建一个：

    • 个人令牌：您的十六进制帐户设置
    • 工作区令牌：工作区管理设置（用于程序化访问）

  2. Node.js：版本18或更高版本

配置

环境变量

将您的Hex API令牌设置为环境变量：

export HEX_API_TOKEN="your-hex-api-token"

Claude桌面配置

将服务器添加到Claude Desktop配置文件中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "hex": {
      "command": "npx",
      "args": ["@olivia/hex-mcp-server"],
      "env": {
        "HEX_API_TOKEN": "your-hex-api-token"
      }
    }
  }
}

可用工具

项目运营

hex_list_projects

列出所有支持分页的可查看十六进制项目。

参数：

  • limit （可选）：要返回的最大项目数（1-100，默认值：50）
  • offset （可选）：分页偏移量（默认值：0）
  • statusFilter （可选）：按项目状态筛选[“已发布”、“草稿”、“计划”]

例子：

{
  "limit": 10,
  "offset": 0,
  "statusFilter": ["published"]
}

hex_get_project

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

参数：

  • projectId （必填）：要检索的项目的ID

运行操作

hex_run_project

使用可选输入参数执行已发布的十六进制项目。

参数：

  • projectId （必填）：要运行的项目的ID
  • inputs （可选）：输入项目运行的参数
  • updateCache （可选）：是否更新缓存（默认值：true）
  • notifyWhenNotPending （可选）：当运行不再处于挂起状态时发送通知
  • dryRun （可选）：模拟运行而不执行

例子：

{
  "projectId": "abc123",
  "inputs": {
    "date_range": "last_7_days",
    "customer_segment": "enterprise"
  }
}

hex_get_run_status

获取项目运行的状态。

参数：

  • projectId （必填）：项目的ID
  • runId （必填）：要检查的跑步ID

hex_cancel_run

取消活动项目运行。

参数：

  • projectId （必填）：项目的ID
  • runId （必填）：要取消的跑步ID

hex_rate_limit_status

获取当前API费率限制状态。

嵌入操作

hex_create_embed_url

为具有自定义选项的十六进制项目生成嵌入URL。

参数：

  • projectId （必填）：要嵌入的项目的ID
  • viewMode （可选）：查看模式[“应用”、“编辑”、“只读”]（默认：“应用”）
  • borderless （可选）：从嵌入视图中删除边框
  • colorMode （可选）：颜色模式[“亮”、“暗”]
  • hideHeader （可选）：隐藏嵌入视图中的标题
  • hideSidebar （可选）：在嵌入式视图中隐藏侧边栏
  • inputs （可选）：嵌入式项目的预填输入值

例子：

{
  "projectId": "abc123",
  "viewMode": "app",
  "colorMode": "dark",
  "inputs": {
    "metric": "revenue"
  }
}

使用示例

使用克劳德桌面

配置后，您可以要求Claude：

  • “列出我的十六进制项目”
  • “使用上个月的数据运行销售仪表板项目”
  • “检查运行分析的状态”
  • “为客户分析仪表板创建嵌入URL”

程序化使用

import { HexApiClient } from '@olivia/hex-mcp-server';

const client = new HexApiClient(process.env.HEX_API_TOKEN);

// List projects
const { projects } = await client.listProjects({ limit: 10 });

// Run a project
const run = await client.runProject('project-id', {
  inputs: { date: '2024-01-01' }
});

// Check run status
const status = await client.getRunStatus('project-id', run.runId);

速率限制

API十六进制具有以下速率限制：

  • 一般：每分钟60个请求
  • 项目运行：每分钟20个请求
  • 最多25个并发运行的内核

使用 hex_rate_limit_status 监控您当前使用情况的工具。

错误处理

服务器为以下对象提供详细的错误消息：

  • 无效的API令牌
  • 超出速率限制（429个错误）
  • 项目ID无效
  • 请求格式错误
  • 网络问题

发展

从源头构建

npm install
npm run build

在发展中奔跑

npm run dev

运行测试

npm test

安全

  • API令牌通过环境变量传递，而不是通过命令行参数传递
  • 服务器只能访问API令牌可见的项目
  • 所有API通信都通过HTTPS

贡献

欢迎投稿！拜托：

  1. 分叉存储库
  2. 创建要素分支
  3. 添加新功能的测试
  4. 提交拉取请求

许可证

麻省理工学院

支持

对于问题和功能请求，请使用GitHub问题跟踪器。

有关Hex API文档，请访问：https://learn.hex.tech/docs/api/api-overview

相关 MCP