ListenHub MCP
EN中文

Listenhub MCP Guide

Complete integration guide covering client setup, examples, transport modes, and available tools.

ListenHub provides an official MCP Server for AI podcast generation (single host or dual host), FlowSpeech, and related capabilities. This server is available to users on Pro plan or above.

Quick Start

Environment Setup

Install Node.js first.

The MCP server requires Node.js 18 or newer. If Node.js is not installed yet, follow one of the options below.

  • macOS

    Option 1: Official installer

    1. Visit the Node.js website and download an LTS release, for example v24.11.0 (LTS)
    2. Open the downloaded .pkg file and follow the installer
    3. Verify installation in terminal:
    node --version
npm --version

    Option 2: Homebrew

    If Homebrew is not installed, install it with:

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

    Then install Node.js:

    brew install node

    Verify installation:

    node --version
npm --version

  • Windows

    Option 1: Official installer

    1. Visit the Node.js website
    2. Download the Windows LTS version
    3. Run the downloaded .msi installer
    4. Follow the setup wizard
    5. Verify installation in PowerShell:
    node --version
npm --version

    Option 2: winget

    For Windows 10 version 1809 or newer:

    winget install OpenJS.NodeJS.LTS

    Verify installation:

    node --version
npm --version

    Option 3: Chocolatey

    If Chocolatey is available:

    choco install nodejs-lts

    Verify installation:

    node --version
npm --version

  • Linux

    Ubuntu/Debian

    # Install 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

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

    Verify installation:

    node --version
npm --version

Get ListenHub API Key.

Create or view the API key from the ListenHub API Key settings page, then set it as environment variable LISTENHUB_API_KEY.

Client Configuration Methods

  • Claude Desktop

    Edit Claude Desktop config file:

    macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

    Windows: %APPDATA%\\Claude\\claude_desktop_config.json

    Add:

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

    Replace your_api_key_here with the real API key.

  • Cursor

    1. Open Cursor Settings
    2. Navigate to Features -> Model Context Protocol
    3. Click Add MCP Server or edit config file directly

    Config file location:

    • macOS/Linux: ~/.cursor/mcp.json
    • Windows: %APPDATA%\\Cursor\\mcp.json

    Add:

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

    Replace your_api_key_here with the real API key.

    Optional: HTTP transport mode

    Start server manually:

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

    Then configure Cursor:

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

  • Windsurf

    1. Open Windsurf Settings
    2. Navigate to MCP Servers
    3. Add a new server config

    Config file location:

    • macOS/Linux: ~/.windsurf/mcp_server_config.json
    • Windows: %APPDATA%\\Windsurf\\mcp_server_config.json

    Add:

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

    Replace your_api_key_here with the real API key.

  • VS Code (with Cline extension)

    1. Install Cline extension from VS Code Marketplace
    2. Open VS Code Settings
    3. Search for Cline: MCP Settings
    4. Click Edit in settings.json

    Add:

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

    Replace your_api_key_here with the real API key.

  • Zed

    1. Open Zed Settings
    2. Go to MCP section
    3. Edit config file

    Config file location:

    • macOS/Linux: ~/.config/zed/mcp.json
    • Windows: %APPDATA%\\Zed\\mcp.json

    Add:

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

    Replace your_api_key_here with the real API key.

  • Claude CLI

    Run in terminal:

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

    Replace <insert-your-api-key-here> with the real API key.

  • Codex CLI

    Run in terminal:

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

    Replace <insert-your-api-key-here> with the real API key.

  • ChatWise

    1. Open ChatWise settings, choose MCP, and click + to add a new MCP service
    2. Fill in MCP config fields:

    ChatWise MCP configuration

    • Command: npx -y @marswave/listenhub-mcp-server@latest
    • Enable Run tools automatically
    • Add environment variable LISTENHUB_API_KEY with your key value
    1. Enable tools from the chat input area and start using them

  • Other MCP clients

    For other MCP-compatible clients, use the standard MCP format:

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

    Replace your_api_key_here with the real API key.

Usage Examples

Generate a Chinese podcast:

Generate Chinese podcast

Generate an English podcast:

Generate English podcast

Core Capabilities

  • Podcast generation

    • Supports full generation (text + audio) or text-only generation
    • Supports 1 to 2 speakers with customizable voices
    • Provides multiple generation modes: quick, deep, and debate
    • Supports script-first generation flow (text then audio)
    • Accepts text and URL as content sources
    • Supports podcast status querying
    • Returns audio file, title, scripts, outline, and related metadata
    • Tracks credit usage

  • FlowSpeech generation

    • Converts text or URL content into conversational single-speaker audio
    • Supports smart mode (AI-enhanced narration) and direct mode (verbatim reading)
    • Supports FlowSpeech status querying
    • Returns audio file, title, scripts, outline, and related metadata
    • Tracks credit usage

  • Voice management

    • Browse available voices library
    • Filter by language and voice attributes
    • Retrieve voice ID, name, language, gender, and demo audio

  • User account information

    • Check subscription status and plan details
    • View credit usage by monthly, permanent, and limited-time credits
    • Monitor total available credits and renewal status
    • View subscription start and expiration dates

  • Multiple transports

    • Supports Stdio, HTTP SSE, and HTTP Streamable transport for flexible integration

Transport Modes

The server supports multiple transport modes for different integration scenarios.

Stdio Mode (Default)

Standard input and output communication. This is the default mode used by most MCP clients, including Claude Desktop and Cursor.

All configuration samples above use Stdio mode by default and require no extra settings.

HTTP/SSE Mode

For advanced scenarios, run the server in HTTP mode to expose both HTTP stream and Server-Sent Events (SSE) endpoints.

Start server in HTTP mode:

# 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

Available endpoints:

  • HTTP stream: http://localhost:3000/mcp
  • Server-Sent Events: http://localhost:3000/sse

Configure MCP client to use HTTP endpoint:

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

Available Tools

Speaker Lookup

  • get_speakers - Returns available speakers for podcast generation, including voice ID, name, language, gender, and demo audio link.
    • language: filter by language code (zh or en) (string, optional)

Podcast Generation

  • create_podcast - Creates a full podcast (text + audio). Supports 1 to 2 speakers. Automatically polls until completion, which can take several minutes.

    • query: topic or content prompt (string, optional)
    • sources: array of text/URL sources (array, optional)
    • speakerIds: 1 to 2 speaker IDs (array, required)
    • language: language code zh or en (string, optional, default: en)
    • mode: generation mode quick, deep, or debate (string, optional, default: quick)

  • get_podcast_status - Returns current podcast details immediately without polling.

    • episodeId: podcast episode ID (string, required)

  • create_podcast_text_only - Creates a text-only podcast as the first phase of the script-first workflow.

    • query: topic or content prompt (string, optional)
    • sources: array of text/URL sources (array, optional)
    • speakerIds: 1 to 2 speaker IDs (array, required)
    • language: language code zh or en (string, required)
    • mode: generation mode quick, deep, or debate (string, optional, default: quick)
    • waitForCompletion: wait until text generation completes (boolean, optional, default: true)

  • generate_podcast_audio - Generates audio for an existing text-only podcast as the second phase of the script-first workflow.

    • episodeId: podcast episode ID (string, required)
    • customScripts: custom scripts array (array, optional)
    • waitForCompletion: wait until audio generation completes (boolean, optional, default: true)

FlowSpeech Generation

  • create_flowspeech - Creates FlowSpeech from text or URL content. Supports smart mode (AI enhancement) and direct mode (no content modification).

    • sourceType: source type text or url (string, required)
    • sourceContent: source content (text or URL) (string, required)
    • speakerId: narration speaker ID (string, required)
    • language: language code zh or en (string, optional)
    • mode: generation mode smart or direct (string, optional, default: smart)

  • get_flowspeech_status - Returns current FlowSpeech details immediately without polling.

    • episodeId: FlowSpeech episode ID (string, required)

User Subscription Lookup

  • get_user_subscription - Returns current user subscription information, including status, credit usage, plan details, and renewal status.

Thanks for using ListenHub MCP Server.

For support, contact: support@marswave.ai

On this page

Quick StartEnvironment SetupClient Configuration MethodsUsage ExamplesCore CapabilitiesTransport ModesStdio Mode (Default)HTTP/SSE ModeAvailable ToolsSpeaker LookupPodcast GenerationFlowSpeech GenerationUser Subscription Lookup