MCP 服务器

RunningHub MCP Server

A FastMCP-based server providing a comprehensive toolset for the RunningHub AI application platform. It enables users to configure nodes, upload media, submit AI tasks, and manage task execution and results through persistent storage.

README

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