README.md
RunningHub MCP Server
基于 FastMCP 框架的 MCP 服务，为 RunningHub AI 应用平台提供完整的工具集。
功能概览
- 节点查询 - 获取 AI 应用的可配置节点列表
- 文件上传 - 上传图片/音频/视频到 RunningHub 平台
- 任务提交 - 提交 AI 应用任务并获取 taskId
- 结果查询 - 查询任务执行状态和输出结果
- 一键执行 - 提交任务并自动轮询等待完成
- 任务管理 - 基于本地 JSON 文件的任务持久化管理
安装
# 使用 uv（推荐）
cd runninghub-mcp
uv sync
# 或使用 pip
pip install -e .
配置
通过环境变量配置服务：
| 环境变量 | 必需 | 默认值 | 说明 |
|---|---|---|---|
RUNNINGHUB_API_KEY |
是 | - | RunningHub API 密钥 |
RUNNINGHUB_API_HOST |
否 | www.runninghub.cn |
API 主机地址 |
RUNNINGHUB_TASK_STORE_PATH |
否 | ~/.runninghub/tasks.json |
任务持久化文件路径 |
MCP 客户端配置示例
Cursor / Claude Desktop (mcp.json)
{
"mcpServers": {
"runninghub": {
"command": "uv",
"args": ["--directory", "/path/to/runninghub-mcp", "run", "runninghub-mcp"],
"env": {
"RUNNINGHUB_API_KEY": "your-api-key"
}
}
}
}
Tool 列表
原子工具（API 端点）
| Tool | 说明 | 关键参数 |
|---|---|---|
get_node_info |
获取 AI 应用的可配置节点列表 | webapp_id |
upload_file |
上传文件到 RunningHub | file_path |
submit_task |
提交 AI 应用任务 | webapp_id, node_info_list |
query_task_outputs |
查询任务状态和输出结果 | task_id |
完整流程工具
| Tool | 说明 |
|---|---|
run_task_and_wait |
提交任务并轮询等待完成，支持自定义超时和轮询间隔 |
持久化管理工具
| Tool | 说明 | 关键参数 |
|---|---|---|
list_tasks |
查询本地存储的任务列表 | status(可选), limit |
get_task_detail |
获取指定任务的详细信息 | task_id |
sync_task_status |
从 API 同步任务最新状态到本地 | task_id |
使用流程
典型的使用流程如下：
- 调用
get_node_info获取 AI 应用的节点列表 - 根据需要修改节点参数（如需上传文件，先调用
upload_file） - 调用
run_task_and_wait提交任务并等待结果（或分步使用submit_task+query_task_outputs） - 使用
list_tasks/get_task_detail查看历史任务
项目结构
src/runninghub_mcp/
__init__.py # 包入口
server.py # FastMCP 服务实例 + Tool 定义 + 入口
api.py # RunningHub HTTP API 封装
storage.py # 任务持久化管理（JSON 文件）
models.py # 数据模型定义
开发
# 安装开发依赖
uv sync
# 直接运行服务（STDIO 模式）
RUNNINGHUB_API_KEY=your-key uv run runninghub-mcp
# 使用 fastmcp dev 调试
RUNNINGHUB_API_KEY=your-key uv run fastmcp dev src/runninghub_mcp/server.py
Tools 8
get_node_infoGet the list of configurable nodes for an AI application.upload_fileUpload files to the RunningHub platform.submit_taskSubmit an AI application task.query_task_outputsQuery the execution status and output results of a task.run_task_and_waitSubmit a task and automatically poll until completion.list_tasksQuery the locally stored task list.get_task_detailGet detailed information for a specific task.sync_task_statusSync the latest task status from the API to local storage.Environment Variables
RUNNINGHUB_API_KEYrequiredRunningHub API keyRUNNINGHUB_API_HOSTAPI host addressRUNNINGHUB_TASK_STORE_PATHPath for task persistence fileTry it
→Get the available node information for the AI application with ID 123.
→Upload the image at ./my_photo.jpg to RunningHub.
→Submit a new task for webapp 123 and wait for it to finish.
→List all my recent tasks and check their current status.
→Sync the status of task ID 456 to see if it has finished processing.