Listenhub MCP Server

🚀 ListenHub MCP Server

ListenHub MCP Server是ListenHub的官方MCP服务器，支持AI播客生成（单播或双播）、FlowSpeech创建等功能。此服务仅对ListenHub专业版及以上套餐用户开放。

English | 简体中文

🚀 快速开始

环境配置

安装Node.js

此服务器需要Node.js 18或更高版本。若您尚未安装Node.js，请按以下说明操作：

• macOS系统 方法一：使用官方安装程序

  1. 访问 Node.js官方网站，下载Node.js长期支持版本，例如 v24.11.0(LTS)。
  2. 打开下载的 .pkg 文件，按照安装向导完成安装。
  3. 打开终端，运行以下命令验证安装：

  node --version
  npm --version
  

  方法二：使用Homebrew 若您未安装 Homebrew，可使用以下脚本进行安装：

  /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
  

  # 安装成功后，使用brew下载Node.js
  brew install node
  

  然后验证安装：

  node --version
  npm --version
  

• Windows系统 方法一：使用官方安装程序

  1. 访问 Node.js官方网站。
  2. 下载适用于Windows的LTS（长期支持）版本。
  3. 运行下载的 .msi 安装程序。
  4. 按照安装向导完成安装。
  5. 打开PowerShell，运行以下命令验证安装：

  node --version
  npm --version
  

  方法二：使用winget（Windows包管理器） 若您使用的是Windows 10 1809或更高版本：

  winget install OpenJS.NodeJS.LTS
  

  然后验证安装：

  node --version
  npm --version
  

  方法三：使用Chocolatey 若您已安装Chocolatey：

  choco install nodejs-lts
  

  然后验证安装：

  node --version
  npm --version
  

• Linux系统 Ubuntu/Debian系统

  # 安装Node.js 20.x (LTS)
  curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
  sudo apt-get install -y nodejs
  

  Fedora/RHEL/CentOS系统

  # 安装Node.js 20.x (LTS)
  curl -fsSL https://rpm.nodesource.com/setup_20.x | sudo bash -
  sudo yum install -y nodejs
  

  验证安装：

  node --version
  npm --version
  

获取ListenHub API密钥

您可以从 ListenHub API密钥设置 页面获取API密钥，并将其作为 LISTENHUB_API_KEY 环境变量的值。

各客户端配置方法

• Claude Desktop 编辑Claude Desktop配置文件： macOS系统：~/Library/Application Support/Claude/claude_desktop_config.json Windows系统：%APPDATA%\Claude\claude_desktop_config.json 添加以下配置：

  {
    "mcpServers": {
      "listenhub": {
        "command": "npx",
        "args": ["-y", "@marswave/listenhub-mcp-server@latest"],
        "env": {
          "LISTENHUB_API_KEY": "your_api_key_here"
        }
      }
    }
  }
  

  将 your_api_key_here 替换为您从ListenHub获取的实际API密钥。

• Cursor

  1. 打开Cursor设置。
  2. 导航至 功能 → 模型上下文协议。
  3. 点击 添加MCP服务器 或直接编辑配置文件。 配置文件位置：
  • macOS/Linux系统：~/.cursor/mcp.json
  • Windows系统：%APPDATA%\Cursor\mcp.json 添加以下配置：

  {
    "mcpServers": {
      "listenhub": {
        "command": "npx",
        "args": ["-y", "@marswave/listenhub-mcp-server@latest"],
        "env": {
          "LISTENHUB_API_KEY": "your_api_key_here"
        }
      }
    }
  }
  

  将 your_api_key_here 替换为您从ListenHub获取的实际API密钥。 可选：HTTP模式 若要使用HTTP传输，需手动启动服务器：

  export LISTENHUB_API_KEY="your_api_key_here"
  npx @marswave/listenhub-mcp-server --transport http --port 3000
  

  然后配置Cursor：

  {
    "mcpServers": {
      "listenhub": {
        "url": "http://localhost:3000/mcp"
      }
    }
  }
  

• Windsurf

  1. 打开Windsurf设置。
  2. 导航至 MCP服务器 部分。
  3. 添加新的服务器配置。 配置文件位置：
  • macOS/Linux系统：~/.windsurf/mcp_server_config.json
  • Windows系统：%APPDATA%\Windsurf\mcp_server_config.json 添加以下配置：

  {
    "mcpServers": {
      "listenhub": {
        "command": "npx",
        "args": ["-y", "@marswave/listenhub-mcp-server@latest"],
        "env": {
          "LISTENHUB_API_KEY": "your_api_key_here"
        }
      }
    }
  }
  

  将 your_api_key_here 替换为您从ListenHub获取的实际API密钥。

• VS Code（通过Cline扩展）

  1. 从VS Code市场安装 Cline扩展。
  2. 打开VS Code设置。
  3. 搜索 “Cline: MCP设置”。
  4. 点击 “在settings.json中编辑”。 添加以下配置：

  {
    "cline.mcpServers": {
      "listenhub": {
        "command": "npx",
        "args": ["-y", "@marswave/listenhub-mcp-server@latest"],
        "env": {
          "LISTENHUB_API_KEY": "your_api_key_here"
        }
      }
    }
  }
  

  将 your_api_key_here 替换为您从ListenHub获取的实际API密钥。

• Zed Editor

  1. 打开Zed设置。
  2. 导航至MCP部分。
  3. 编辑配置文件。 配置文件位置：
  • macOS/Linux系统：~/.config/zed/mcp.json
  • Windows系统：%APPDATA%\Zed\mcp.json 添加以下配置：

  {
    "mcpServers": {
      "listenhub": {
        "command": "npx",
        "args": ["-y", "@marswave/listenhub-mcp-server@latest"],
        "env": {
          "LISTENHUB_API_KEY": "your_api_key_here"
        }
      }
    }
  }
  

  将 your_api_key_here 替换为您从ListenHub获取的实际API密钥。

• Claude CLI 在终端中运行以下命令：

  claude mcp add listenhub --env LISTENHUB_API_KEY=<insert-your-api-key-here> -- npx -y @marswave/listenhub-mcp-server
  

  将 <insert-your-api-key-here> 替换为您从ListenHub获取的实际API密钥。

• Codex CLI 在终端中运行以下命令：

  codex mcp add listenhub --env LISTENHUB_API_KEY=<insert-your-api-key-here> -- npx -y @marswave/listenhub-mcp-server
  

  将 <insert-your-api-key-here> 替换为您从ListenHub获取的实际API密钥。

• ChatWise

  1. 打开ChatWise设置，选择MCP，点击 “+” 添加新的MCP服务。
  2. 在MCP配置模块中填写以下信息：
     • 命令：npx -y @marswave/listenhub-mcp-server@latest
     • 环境变量：添加 LISTENHUB_API_KEY，并将您的API密钥作为其值。
  3. 在聊天输入框下方启用该工具即可开始使用。

• 其他MCP客户端 对于其他支持MCP的客户端，可使用标准的MCP配置格式：

  {
    "mcpServers": {
      "listenhub": {
        "command": "npx",
        "args": ["-y", "@marswave/listenhub-mcp-server@latest"],
        "env": {
          "LISTENHUB_API_KEY": "your_api_key_here"
        }
      }
    }
  }
  

  将 your_api_key_here 替换为您从ListenHub获取的实际API密钥。

💻 使用示例

基础用法

生成英文播客

✨ 主要特性

• 播客生成：
  • 支持全量生成（文本 + 音频）或仅生成文本。
  • 支持1 - 2个说话人，且可自定义语音。
  • 多种生成模式：快速收听、深度探索、辩论。
  • 支持两阶段生成。
  • 支持文本和URL内容源。
  • 可查询播客生成状态。
  • 可访问音频文件、标题、脚本和大纲。
  • 可跟踪信用消耗情况。
• FlowSpeech语音生成：
  • 可将文本或URL中的书面内容转换为单说话人的对话式音频。
  • 支持智能模式（AI增强阅读）或直接模式（逐字阅读）。
  • 可查询FlowSpeech生成状态。
  • 可访问音频文件、标题、脚本和大纲。
  • 可跟踪信用消耗情况。
• 说话人管理：
  • 可浏览可用的说话人/语音库。
  • 可按语言和说话人属性进行筛选。
  • 可获取说话人的ID、姓名、语言、性别和演示音频。
• 用户账户管理：
  • 可查询订阅状态和套餐信息。
  • 可查看信用使用情况：月度信用、永久信用和限时信用。
  • 可监控总可用信用和续订状态。
  • 可查看订阅开始/到期日期。
• 多种传输模式：支持Stdio、HTTP SSE和HTTP Streamable传输方法，便于灵活集成。

🔧 技术细节

传输模式

该服务器支持多种传输模式，以适应不同的使用场景。

Stdio模式（默认）

标准输入/输出通信。这是大多数MCP客户端（如Claude Desktop、Cursor等）使用的默认模式。 上述所有配置示例默认使用stdio模式，无需额外设置。

HTTP/SSE模式

对于高级使用场景，您可以在HTTP模式下运行服务器，同时提供HTTP流式传输和服务器发送事件（SSE）端点。

在HTTP模式下启动服务器：

# macOS/Linux系统
export LISTENHUB_API_KEY="your_api_key_here"
npx @marswave/listenhub-mcp-server --transport http --port 3000
# Windows系统
set LISTENHUB_API_KEY=your_api_key_here
npx @marswave/listenhub-mcp-server --transport http --port 3000

可用端点：

• HTTP流式传输：http://localhost:3000/mcp
• 服务器发送事件：http://localhost:3000/sse

配置您的MCP客户端以使用HTTP端点：

{
  "mcpServers": {
    "listenhub": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

📚 详细文档

可用工具

说话人查询

• get_speakers - 获取可用于播客生成的说话人列表。返回说话人的ID、姓名、语言、性别和演示音频链接。
  • language：按语言代码（zh/en）进行筛选（字符串，可选）

播客生成

• create_podcast - 创建全量生成（文本 + 音频）的播客。支持1 - 2个说话人。自动轮询直至完成（可能需要几分钟）。
  • query：内容或主题（字符串，可选）
  • sources：文本/URL源数组（数组，可选）
  • speakerIds：1 - 2个说话人ID的数组（数组，必需）
  • language：语言代码 - zh或en（字符串，可选，默认值：en）
  • mode：生成模式 - quick、deep或debate（字符串，可选，默认值：quick）
• get_podcast_status - 查询播客的详细信息。立即返回当前状态，无需轮询。
  • episodeId：播客ID（字符串，必需）
• create_podcast_text_only - 仅创建文本内容的播客（无音频）。两阶段生成的第一阶段。
  • query：内容或主题（字符串，可选）
  • sources：文本/URL源数组（数组，可选）
  • speakerIds：1 - 2个说话人ID的数组（数组，必需）
  • language：语言代码 - zh或en（字符串，必需）
  • mode：生成模式 - quick、deep或debate（字符串，可选，默认值：quick）
  • waitForCompletion：等待生成完成（布尔值，可选，默认值：true）
• generate_podcast_audio - 为已有文本内容的播客生成音频。两阶段生成的第二阶段。
  • episodeId：播客ID（字符串，必需）
  • customScripts：自定义脚本数组（数组，可选）
  • waitForCompletion：等待生成完成（布尔值，可选，默认值：true）

FlowSpeech生成

• create_flowspeech - 将文本或URL内容转换为语音，创建FlowSpeech。支持智能模式（AI增强）和直接模式（无修改）。
  • sourceType：源类型 - text或url（字符串，必需）
  • sourceContent：源内容（文本或URL）（字符串，必需）
  • speakerId：用于旁白的说话人ID（字符串，必需）
  • language：语言代码 - zh或en（字符串，可选）
  • mode：生成模式 - smart或direct（字符串，可选，默认值：smart）
• get_flowspeech_status - 查询FlowSpeech的详细信息。立即返回当前状态，无需轮询。
  • episodeId：FlowSpeech ID（字符串，必需）

用户账户查询

• get_user_subscription - 获取当前用户的订阅信息，包括订阅状态、信用使用情况、套餐详情和续订状态。

感谢使用ListenHub MCP Server！

若您有任何疑问，请随时联系我们：support@marswave.ai