十六进制MCP服务器
MCP（模型上下文协议）服务器，为LLM提供访问Hex API的权限，使人工智能助手能够与Hex项目交互、运行分析和管理数据工作流。
特性
- 项目管理：列出并检索十六进制项目
- 项目执行：使用自定义输入运行项目并监控执行状态
- 嵌入式生成：为Hex项目创建可自定义的嵌入URL
- 速率限制监控：跟踪API使用情况以保持在限制范围内
安装
通过NPX（推荐）
npx @olivia/hex-mcp-server本地安装
npm install @olivia/hex-mcp-server先决条件
- 十六进制API令牌：您需要一个十六进制API令牌。您可以从以下位置创建一个：
- 个人令牌：您的十六进制帐户设置 - 工作区令牌：工作区管理设置（用于程序化访问）
- 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（必填）：要运行的项目的IDinputs（可选）：输入项目运行的参数updateCache（可选）：是否更新缓存（默认值：true）notifyWhenNotPending（可选）：当运行不再处于挂起状态时发送通知dryRun（可选）：模拟运行而不执行
例子：
{
"projectId": "abc123",
"inputs": {
"date_range": "last_7_days",
"customer_segment": "enterprise"
}
}hex_get_run_status
获取项目运行的状态。
参数：
projectId（必填）：项目的IDrunId（必填）：要检查的跑步ID
hex_cancel_run
取消活动项目运行。
参数：
projectId（必填）：项目的IDrunId（必填）：要取消的跑步ID
hex_rate_limit_status
获取当前API费率限制状态。
嵌入操作
hex_create_embed_url
为具有自定义选项的十六进制项目生成嵌入URL。
参数：
projectId（必填）：要嵌入的项目的IDviewMode（可选）：查看模式\[“应用”、“编辑”、“只读”\]（默认：“应用”）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
贡献
欢迎投稿！拜托：
- 分叉存储库
- 创建要素分支
- 添加新功能的测试
- 提交拉取请求
许可证
麻省理工学院
支持
对于问题和功能请求，请使用GitHub问题跟踪器。
有关Hex API文档，请访问：https://learn.hex.tech/docs/api/api-overview