Available Tools

The ListenHub MCP server exposes 8 tools. Each tool wraps an OpenAPI endpoint and returns the unwrapped data payload on success. Underlying responses follow the standard envelope { "code": 0, "message": "", "data": { ... } }; a non-zero code indicates an error.

Speaker Lookup

get_speakers

Returns the available speakers for podcast and FlowSpeech generation, including voice ID, name, language, gender, demo audio link, and a voice profile.

Inputs

• language: filter by language code, zh or en (string, optional)

Response

Returns an items array. Each item carries a speakerId (use this value for speakerIds / speakerId in the other tools).

{
  "items": [
    {
      "name": "Aria",
      "speakerId": "sp_aria_en",
      "demoAudioUrl": "https://storage.googleapis.com/.../aria-demo.mp3",
      "gender": "female",
      "language": "en",
      "profile": {
        "pitch": ["medium", "medium-high"],
        "speed": ["medium-fast"],
        "traits": ["clear", "bright", "warm"],
        "styles": ["friendly", "narrative"],
        "scenes": ["podcast", "audiobook"],
        "accent": "American English",
        "description": "Warm, conversational host voice.",
        "descriptionLocalized": { "zh": "温暖、口语化的主持人声音。" }
      }
    }
  ]
}

Podcast Generation

create_podcast

Creates a full podcast (text + audio). Polls automatically until completion, which can take several minutes.

Inputs

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

Provide at least one of query or sources.

Response

Because this tool polls to completion, it returns the full podcast detail (the same shape as get_podcast_status). A representative completed payload:

{
  "episodeId": "664e0c2b9f1a2b3c4d5e6f70",
  "createdAt": 1716460000000,
  "processStatus": "success",
  "contentStatus": "audio-success",
  "completedTime": 1716460320000,
  "credits": 12,
  "title": "How LLMs Changed Search",
  "outline": "1. The shift from keywords...",
  "cover": "https://storage.googleapis.com/.../cover.png",
  "audioUrl": "https://storage.googleapis.com/.../episode.mp3",
  "audioStreamUrl": "https://storage.googleapis.com/.../episode-stream.mp3",
  "subtitlesUrl": "https://storage.googleapis.com/.../episode.srt",
  "scripts": [
    { "speakerId": "sp_aria_en", "speakerName": "Aria", "content": "Welcome back to the show." },
    { "speakerId": "sp_leo_en", "speakerName": "Leo", "content": "Today we're digging into search." }
  ]
}

get_podcast_status

Returns current podcast details immediately, without polling.

Inputs

• episodeId: podcast episode ID (string, required)

Response

Same shape as the completed create_podcast payload above. While generation is in progress, processStatus reflects the current state and content fields (audioUrl, scripts, and so on) may be absent until the corresponding phase finishes. contentStatus is one of text-success, text-fail, audio-success, or audio-fail.

{
  "episodeId": "664e0c2b9f1a2b3c4d5e6f70",
  "createdAt": 1716460000000,
  "processStatus": "processing",
  "contentStatus": "text-success",
  "credits": 0,
  "title": "How LLMs Changed Search",
  "outline": "1. The shift from keywords...",
  "scripts": [
    { "speakerId": "sp_aria_en", "speakerName": "Aria", "content": "Welcome back to the show." }
  ]
}

create_podcast_text_only

Creates a text-only podcast (script, no audio). This is the first phase of the script-first workflow: generate the script, review or edit it, then call generate_podcast_audio.

Inputs

• query: topic or content prompt (string, optional)
• sources: array of text/URL sources (array, optional)
• speakerIds: 1 to 2 speaker IDs (array, required). Provide 2 IDs for debate mode.
• 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)

Provide at least one of query or sources.

Response

Returns the new episodeId and a status message. When waitForCompletion is true, the tool waits for the script to finish before returning; query the script with get_podcast_status.

{
  "episodeId": "664e0c2b9f1a2b3c4d5e6f70",
  "message": "Text content generation started. Audio generation can be triggered later."
}

generate_podcast_audio

Generates audio for an existing text-only podcast. This is the second phase of the script-first workflow.

Inputs

• episodeId: podcast episode ID (string, required)
• customScripts: custom scripts array (array, optional). Each entry has content (string) and speakerId (string). When omitted, the existing script is used.
• waitForCompletion: wait until audio generation completes (boolean, optional, default: true)

Response

Confirms that audio generation started. Poll get_podcast_status for the finished audioUrl.

{
  "success": true,
  "message": "Audio generation started",
  "episodeId": "664e0c2b9f1a2b3c4d5e6f70",
  "status": "processing"
}

FlowSpeech Generation

create_flowspeech

Creates FlowSpeech (single-speaker narration) from text or a URL. smart mode applies AI enhancement to the source; direct mode reads the content verbatim with no modification.

Inputs

• sourceType: source type text or url (string, required)
• sourceContent: source content — the text body or the URL (string, required). For text, the content must be at least 10 characters.
• speakerId: narration speaker ID (string, required). FlowSpeech uses exactly one speaker.
• language: language code zh or en (string, optional)
• mode: generation mode smart or direct (string, optional, default: smart)

Response

Returns the new episodeId. Generation runs asynchronously; poll with get_flowspeech_status.

{
  "episodeId": "664e0c2b9f1a2b3c4d5e6f71"
}

get_flowspeech_status

Returns current FlowSpeech details immediately, without polling.

Inputs

• episodeId: FlowSpeech episode ID (string, required)

Response

For FlowSpeech, scripts is a single string (the narration script), not the per-speaker array used by podcasts. Content fields appear as each phase finishes.

{
  "episodeId": "664e0c2b9f1a2b3c4d5e6f71",
  "createdAt": 1716460000000,
  "processStatus": "success",
  "completedTime": 1716460120000,
  "title": "Quarterly Product Update",
  "outline": "1. Highlights...",
  "cover": "https://storage.googleapis.com/.../cover.png",
  "audioUrl": "https://storage.googleapis.com/.../flowspeech.mp3",
  "audioStreamUrl": "https://storage.googleapis.com/.../flowspeech-stream.mp3",
  "subtitlesUrl": "https://storage.googleapis.com/.../flowspeech.srt",
  "scripts": "Welcome to the quarterly update. This quarter we shipped..."
}

User Subscription Lookup

get_user_subscription

Returns the current user's subscription and credit balances: plan details, monthly / permanent / limited-time credits, total available credits, renewal status, and subscription dates. Call this before generating to confirm you have enough credits.

Inputs

None.

Response

Timestamps are 13-digit milliseconds. totalAvailableCredits is the sum of the available monthly, permanent, and limited-time credits.

{
  "subscriptionStartedAt": 1714000000000,
  "subscriptionExpiresAt": 1716592000000,
  "usageAvailableMonthlyCredits": 480,
  "usageTotalMonthlyCredits": 500,
  "usageAvailablePermanentCredits": 100,
  "usageTotalPermanentCredits": 100,
  "usageAvailableLimitedTimeCredits": 0,
  "totalAvailableCredits": 580,
  "resetAt": 1716592000000,
  "platform": "web",
  "renewStatus": true,
  "paidStatus": true,
  "subscriptionPlan": {
    "name": "Pro",
    "duration": "monthly",
    "platform": "web"
  }
}

Thanks for using the ListenHub MCP server.

For support, contact: support@marswave.ai