STARWARCLOUD STARWAR.AI
返回市场
希格斯场人工智能MCP服务器

希格斯场人工智能MCP服务器

作者：geopopos2 星标更新：2025-11-04
安装使用来源：spider==github.com

项目介绍

Higgsfield AI MCP Server

一个模型上下文协议（MCP）服务器，提供访问Higgsfield AI的电影级图像和视频生成能力。基于FastMCP构建。

🔧 最近修复 (2025年11月2日)

视频生成现在正确工作了！ generate_video函数已修复以使用正确的API格式：

  • 添加了必需的prompt参数（可选，如果没有提供则自动生成）
  • 修正了API负载结构，从image_url改为input_images数组格式
  • 添加了详细的文档和示例

详情参见父目录中的HIGGSFIELD_VIDEO_GENERATION_GUIDE.md。

功能

  • 文本到图像生成：使用Soul模型创建高质量图像
  • 图像转视频：将静态图像转换为带有运动预设的5秒电影级视频
  • 角色一致性：创建可重复使用的角色参考，以确保跨生成的一致外观
  • 风格预设：浏览并应用电影级风格预设
  • 动作库：访问预先设计的动作效果用于视频生成

安装

先决条件

  • Python 3.10或更高版本
  • pip（Python包管理器）
  • Higgsfield AI账户及API凭证（注册）

设置

  1. 克隆或下载此仓库

  2. 安装依赖项（选择一种方法）：

    选项A：使用pip（推荐简单方式）

    cd higgsfield_ai_mcp
pip install -r requirements.txt

    选项B：使用Poetry

    cd higgsfield_ai_mcp
poetry install

  3. 配置API凭证（选择一种方法）：

    选项A：环境变量（推荐用于.env文件）

    cp .env.example .env

    编辑.env并添加您的Higgsfield AI凭证：

    HF_API_KEY=your-api-key-here
HF_SECRET=your-secret-key-here

    选项B：命令行参数

    直接在运行服务器时传递凭证：

    python -m higgsfield_mcp.server --api-key YOUR_KEY --secret YOUR_SECRET

    获取您的API密钥：https://cloud.higgsfield.ai/api-keys

使用

本地开发与测试

测试服务器：

# 直接使用Python运行
python -m higgsfield_mcp.server

# 或使用命令行参数
python -m higgsfield_mcp.server --api-key YOUR_KEY --secret YOUR_SECRET

# 在开发模式下运行，自动重载（如果使用Poetry）
poetry shell
fastmcp dev src/higgsfield_mcp/server.py

Claude Desktop集成

将此服务器添加到您的Claude Desktop配置中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json

方法1：使用Python直接与环境变量（推荐）

{
  "mcpServers": {
    "higgsfield": {
      "command": "python",
      "args": [
        "-m",
        "higgsfield_mcp.server"
      ],
      "cwd": "/absolute/path/to/higgsfield_ai_mcp",
      "env": {
        "HF_API_KEY": "${HF_API_KEY}",
        "HF_SECRET": "${HF_SECRET}"
      }
    }
  }
}

方法2：使用命令行参数

{
  "mcpServers": {
    "higgsfield": {
      "command": "python",
      "args": [
        "-m",
        "higgsfield_mcp.server",
        "--api-key",
        "${HF_API_KEY}",
        "--secret",
        "${HF_SECRET}"
      ],
      "cwd": "/absolute/path/to/higgsfield_ai_mcp"
    }
  }
}

方法3：使用Poetry（如果您使用Poetry安装）

{
  "mcpServers": {
    "higgsfield": {
      "command": "/Users/YOUR_USERNAME/.local/bin/poetry",
      "args": [
        "run",
        "python",
        "-m",
        "higgsfield_mcp.server"
      ],
      "cwd": "/absolute/path/to/higgsfield_ai_mcp",
      "env": {
        "HF_API_KEY": "${HF_API_KEY}",
        "HF_SECRET": "${HF_SECRET}"
      }
    }
  }
}

注意事项：

  • 将/absolute/path/to/higgsfield_ai_mcp替换为此目录的实际路径
  • 对于方法1和2，确保HF_API_KEY和HF_SECRET在您的shell环境中设置
  • 对于使用Poetry的方法3，使用完整路径（不使用~扩展）
  • 添加配置后，请重启Claude Desktop

FastMCP云部署

部署到FastMCP云以进行远程访问：

# 安装FastMCP CLI
pip install fastmcp

# 部署（需要FastMCP云账户）
fastmcp deploy src/higgsfield_mcp/server.py

可用工具

generate_image

从文本提示生成高质量图像。

参数：

  • prompt（必需）：详细的文字描述
  • quality： "720p" 或 "1080p"（默认）
  • character_id：可选的角色参考ID，用于一致性
  • style_id：可选的风格预设ID

示例：

生成图像："一位眼神锐利的女性坐在沙漠花园中的极简主义长凳上，穿着沙色套装，傍晚的阳光"

generate_video

将图像转换为带有动作效果的电影级视频。

参数：

  • image_url（必需）：源图像URL（必须通过HTTPS公开访问）
  • motion_id（必需）：动作预设ID（使用higgsfield://motions资源浏览）
  • prompt（可选）：图像/场景的描述。如果没有提供，则自动生成。
  • quality： "lite"，"turbo" 或 "standard"（默认）

示例：

generate_video(
  image_url="https://cdn.example.com/beach-selfie.png",
  motion_id="31177282-bde3-4870-b283-1135ca0a201a",
  prompt="一位女性在海滩建筑工地自拍",
  quality="turbo"
)

重要注意事项：

  • 图像URL必须是公开可访问的（Higgsfield服务器需要下载它）
  • 处理时间取决于质量，大约需要20-60秒
  • 每10秒轮询一次get_generation_status以检查完成情况
  • 结果缓存7天

create_character

创建一个可重复使用的角色参考，以确保生成的一致性。

参数：

  • name（必需）：角色的描述性名称
  • image_urls（必需）：显示脸部的1-5张图像URL列表

费用：40积分（$2.50）

get_generation_status

检查作业状态并检索结果。

参数：

  • job_set_id（必需）：来自generate_image/generate_video的作业ID

作业状态：

  • queued：等待开始
  • in_progress：正在生成
  • completed：已完成！结果可用
  • failed：生成失败
  • nsfw：内容过滤器触发

list_characters

列出您创建的所有角色参考及其ID和状态。

可用资源

使用MCP资源浏览数据源：

  • higgsfield://styles：可用的Soul图像风格预设
  • higgsfield://motions：DoP模型的视频动作预设
  • higgsfield://characters：您创建的角色参考

工作流程示例

  1. 浏览可用风格：

    • 访问higgsfield://styles资源查看风格选项

  2. 生成图像：

    generate_image(
  prompt="现代办公室的专业头像",
  quality="1080p",
  style_id="1cb4b936-77bf-4f9a-9039-f3d349a4cdbe"
)

    → 返回job_set_id

  3. 检查状态并获取结果：

    get_generation_status(job_set_id="...")

    → 当完成时返回下载URL

  4. 创建角色以确保一致性（可选）：

    create_character(
  name="Jane Doe",
  image_urls=["https://example.com/face1.jpg", "https://example.com/face2.jpg"]
)

    → 返回character_id

  5. 使用角色生成：

    generate_image(
  prompt="同一个人在不同场景中",
  character_id="3eb3ad49-775d-40bd-b5e5-38b105108780"
)

  6. 动画化结果：

    • 浏览higgsfield://motions以查找动作预设
    generate_video(
  image_url="https://result-from-step-5.jpg",
  motion_id="motion-preset-id",
  quality="standard"
)

定价

当生成成功完成时收取积分（失败时不收费）：

  • 图像生成（Soul）：

    • 720p：1.5积分（$0.09）每张图像
    • 1080p：3积分（$0.19）每张图像
    • 前1000次生成：1积分（$0.06）用于1080p

  • 视频生成（DoP）：

    • Lite：2积分（$0.125）
    • Turbo：6.5积分（$0.406）- 速度加倍
    • Standard：9积分（$0.563）- 最高质量

  • 角色创建：40积分（$2.50）一次性

汇率：$1 = 16积分 在以下网址添加积分：https://cloud.higgsfield.ai/credits

故障排除

"缺少必需的环境变量"

  • 确保存在.env文件，并包含HF_API_KEY和HF_SECRET
  • 或者在您的shell或Claude Desktop配置中设置环境变量

"401未授权"

  • 验证您的API密钥和秘密是否正确
  • 检查它们是否未过期或被撤销

"402支付所需"

服务器未出现在Claude Desktop

  • 检查cwd路径是否为绝对路径，而非相对路径
  • 验证Poetry是否已安装且可访问
  • 在更改配置后重启Claude Desktop
  • 检查Claude Desktop的日志以查找错误

生成卡在“排队”状态

  • 等待几秒钟后再次轮询
  • 检查您的账户是否有足够的积分
  • 在高负载期间，作业可能需要更长时间

项目结构

mcp_creator/
├── src/
│   └── higgsfield_mcp/
│       ├── __init__.py
│       ├── server.py          # FastMCP服务器，包含工具和资源
│       └── client.py          # 异步Higgsfield API封装
├── pyproject.toml             # Poetry配置
├── .env.example               # 凭证模板
├── .env                       # 您的凭证（git忽略）
├── .gitignore
└── README.md

开发

运行测试

poetry shell
fastmcp dev src/higgsfield_mcp/server.py

添加新工具

编辑src/higgsfield_mcp/server.py并添加新的@mcp.tool装饰函数。

添加新API方法

编辑src/higgsfield_mcp/client.py以添加新的API客户端方法。

资源

许可证

MIT许可证 - 查看LICENSE文件了解详情

贡献

欢迎贡献！请打开问题或拉取请求。

支持