HuntAPI

HuntAPI MCP 服务

面向 HuntAPI 媒体下载 API 的官方 Model Context Protocol 服务。

通过一个异步 REST API，从公开媒体 URL 下载视频和音频，或提取其元数据。

Claude、Cursor、VS Code、Windsurf 和任何 MCP 客户端都可以将其作为工具调用 API。支持通过 stdio（本地）或 Streamable HTTP（可自托管）运行。

要求

• Node.js 20 或更高版本
• HuntAPI API 密钥 — 注册，然后从控制面板复制密钥

托管服务（推荐）

HuntAPI 会为你运行此服务，地址为 https://mcp.huntapi.com/（Streamable HTTP）。在 x-api-key 标头中发送你的 API 密钥；无需安装任何内容。

claude mcp add --transport http huntapi https://mcp.huntapi.com/ --header "x-api-key: YOUR_API_KEY"

{
  "mcpServers": {
    "huntapi": {
      "url": "https://mcp.huntapi.com/",
      "headers": {
        "x-api-key": "YOUR_API_KEY"
      }
    }
  }
}

托管服务与此软件包提供相同的 API；如果你需要使用 stdio、自己的网络出口，或想要自托管，请在本地运行此软件包。

在本地运行

Claude Code

claude mcp add huntapi --env HUNTAPI_API_KEY=YOUR_API_KEY -- npx -y @huntapi/mcp

Claude Desktop、Cursor、Windsurf 和其他客户端

将服务添加到客户端的 MCP 配置（claude_desktop_config.json、.cursor/mcp.json…）：

{
  "mcpServers": {
    "huntapi": {
      "command": "npx",
      "args": ["-y", "@huntapi/mcp"],
      "env": {
        "HUNTAPI_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

VS Code

{
  "servers": {
    "huntapi": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@huntapi/mcp"],
      "env": {
        "HUNTAPI_API_KEY": "${input:huntapi-api-key}"
      }
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "huntapi-api-key",
      "description": "HuntAPI API key",
      "password": true
    }
  ]
}

Claude Desktop 扩展

从发布页面下载 .mcpb 包并打开；Claude Desktop 会提示你输入 API 密钥。

Docker

docker build -t huntapi-mcp .
docker run -i --rm -e HUNTAPI_API_KEY=YOUR_API_KEY huntapi-mcp

工具

工具	说明
audio_download	通过 HuntAPI 从 URL 下载音频，并获取任务 ID。
jobs	查询异步 HuntAPI 任务的状态、进度（0–100）和结果。
media_metadata	从媒体 URL 提取元数据，不下载文件。
stats	查询过去一小时内某个引擎或端点的基础设施运行状况。不按你的账户或租户范围筛选。需为每个账户单独启用：HTTP 403 表示请联系支持团队以启用此功能。
usage	获取 Huntapi 账户的实时用量统计信息和积分余额。
video_download	视频下载
wait_for_job	等待异步下载任务完成。

每个调用 API 的工具都会消耗积分。JSON 结果以文本形式返回；图片以内联形式返回，其他文件（PDF……）则作为嵌入资源返回，最大为 4 MB。

Streamable HTTP

npx @huntapi/mcp --http --port 3000

端点为 POST /mcp（无状态，返回 JSON）。每个客户端都在 x-api-key 标头（或 Authorization: Bearer <key>）中发送自己的密钥；服务本身不会使用自己的密钥。默认绑定到 127.0.0.1，并拒绝浏览器来源，除非你将其加入允许列表——对外开放前，请先在其前方配置 TLS。

createHttpHandler() 已导出，可用于兼容 Fetch 的运行时（Cloudflare Workers、Deno、Bun）：

import { createHttpHandler } from "@huntapi/mcp";

export default { fetch: createHttpHandler({ allowedOrigins: [] }) };

安全性

• API 密钥从 HUNTAPI_API_KEY（stdio）或请求标头（HTTP）中读取，并会从错误消息中移除。
• 从网站获取的内容不可信：服务端指示模型将其视为数据，而非指令。
• 如需报告漏洞，请参阅 SECURITY.md。

开发

npm install
npm test
npm run build
npx @modelcontextprotocol/inspector node dist/stdio.js

基于 SDK 构建

该服务使用官方 Node.js SDK（@huntapi/sdk）。

所有 HuntAPI SDK

SDK	Package	Install
Node.js	@huntapi/sdk	npm install @huntapi/sdk
Python	huntapi	pip install huntapi
Go	huntapi-go	go get github.com/huntapi/huntapi-go
.NET	HuntApi	dotnet add package HuntApi
Ruby	huntapi	gem install huntapi
PHP	huntapi/sdk	composer require huntapi/sdk
Java	huntapi-java	从源代码构建，参见其 README
CLI	@huntapi/cli	npm install -g @huntapi/cli
MCP 服务	@huntapi/mcp	npx -y @huntapi/mcp

许可证

MIT — 参见 LICENSE。