# Libsyn MCP tools

> Every Libsyn MCP tool on the Cotlet server: tool names, input schemas, a tools/call example and an example result for each tool.

Source: https://cotlet.dev/docs/mcp/libsyn

Docs sections: [Get started](https://cotlet.dev/docs.md) · [REST API](https://cotlet.dev/docs/api.md) · [MCP](https://cotlet.dev/docs/mcp.md) · [SDKs & CLI](https://cotlet.dev/docs/sdks.md) · [Integrations](https://cotlet.dev/docs/integrations.md)

14 tools for Libsyn on the Cotlet MCP server. Your agent picks them from tools/list.

- MCP server: `https://cotlet.dev/mcp/v1`
- Connects with: Your own Libsyn account (the account owner or a user with publishing rights)
- Integration page: https://cotlet.dev/integrations/libsyn-api-mcp-server

## Endpoints

| Endpoint | Access | Description |
|---|---|---|
| `libsyn_list_shows` | read | Podcasts in your Libsyn account with show ID, title and plan. |
| `libsyn_list_episodes` | read | Episodes of a show, newest first, with status, release date and ad count. |
| `libsyn_get_episode` | read | Title, description (show notes), status, release date, season, episode number, type, rating, author and media file info. |
| `libsyn_get_show_stats` | read | Show downloads: all time, this week, this month, and per day for a date range. |
| `libsyn_get_episode_stats` | read | Downloads in the first 7, 30 and 90 days, all time, and per day for a date range. |
| `libsyn_get_downloads_breakdown` | read | Downloads split by country, listening app or publishing destination. Advanced Plan and higher. |
| `libsyn_export_stats_report` | read | Stats Export as a download link: one file per report, zipped. Advanced Plan and higher. |
| `libsyn_upload_media` | write | Add an audio, video or PDF file to your media library from a URL. Nothing is published. |
| `libsyn_create_episode` | write | New episode saved as a Draft. Nothing reaches listeners until you schedule or publish it. |
| `libsyn_update_episode` | write | Change the title, show notes or details of a draft or published episode; the RSS feed updates. |
| `libsyn_bulk_edit_episodes` | write | Set author or season on many episodes at once and renumber them in order. |
| `libsyn_upload_transcript` | write | Attach an SRT or VTT transcript; Libsyn adds it to the feed for Apple Podcasts and other apps. |
| `libsyn_schedule_episode` | write | Release a draft at a set time to every destination your show is connected to. |
| `libsyn_publish_episode` | write | Publish a draft now to every destination your show is connected to. |

## List shows

MCP tool: `libsyn_list_shows`

Access: read.

Returns every podcast your Libsyn account can open, with its show ID, title and plan. Use the show_id from each item as the show_id parameter of the other tools. If you have one show, the other tools default to it.

### Parameters

No parameters.

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "libsyn_list_shows",
    "arguments": {}
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "shows": [
      {
        "show_id": "412907",
        "title": "The Solo Founder Show",
        "plan": "Advanced"
      },
      {
        "show_id": "518344",
        "title": "Founder Shorts",
        "plan": "Basic"
      }
    ]
  },
  "isError": false
}
```

## List episodes

MCP tool: `libsyn_list_episodes`

Access: read.

Lists episodes of one show, newest first, with status (draft, scheduled or published) and release date, as in the dashboard Episodes list. Filter by status or match titles with search. Pages hold up to 100 episodes; pass next_cursor back as cursor for the next page.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `show_id` | string | no | Show ID from list_shows. Default: your only or first show. |
| `status` | enum | no | all, draft, scheduled or published. Default: all. |
| `search` | string | no | Match episode titles. |
| `limit` | integer | no | 1 to 100. Default: 25. |
| `cursor` | string | no | Next page cursor from the previous call. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "libsyn_list_episodes",
    "arguments": {}
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "episodes": [
      {
        "episode_id": "38415502",
        "title": "Pricing your first product",
        "status": "scheduled",
        "release_at": "2026-10-15T06:00:00-04:00",
        "ads": 0
      },
      {
        "episode_id": "38201877",
        "title": "Your first ten customers",
        "status": "published",
        "release_at": "2026-10-01T06:00:00-04:00",
        "ads": 2
      }
    ],
    "next_cursor": "eyJvZmZzZXQiOjI1fQ"
  },
  "isError": false
}
```

## Get episode

MCP tool: `libsyn_get_episode`

Access: read.

Returns one episode with its full show notes, status, release date, season and episode number, type, rating, author, tags and media file. Use it before update_episode so your agent edits the current text and does not overwrite it.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `episode_id` | string | yes | Episode ID from list_episodes. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "libsyn_get_episode",
    "arguments": {
      "episode_id": "episode_8c41d2"
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "episode_id": "38415502",
    "title": "Pricing your first product",
    "description": "How to price your first product.",
    "status": "scheduled",
    "release_at": "2026-10-15T06:00:00-04:00",
    "season_number": 3,
    "episode_number": 12,
    "episode_type": "full",
    "rating": "clean",
    "author": "Dana Kim",
    "tags": [
      "pricing",
      "startups"
    ],
    "media_file": {
      "file_name": "ep-142.mp3",
      "media_file_id": "f_88120"
    }
  },
  "isError": false
}
```

## Get show stats

MCP tool: `libsyn_get_show_stats`

Access: read.

Returns downloads for the whole show: all time, this week, this month and per day for the range you choose. The metric is IAB downloads by default, or unique downloads. Read only.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `show_id` | string | no | Show ID from list_shows. Default: your only or first show. |
| `start_date` | date | no | First day of the range. Default: 30 days ago. |
| `end_date` | date | no | Last day of the range. Default: today. |
| `metric` | enum | no | iab or unique downloads. Default: iab. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "libsyn_get_show_stats",
    "arguments": {}
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "show_id": "412907",
    "metric": "iab",
    "all_time": 214530,
    "this_week": 1260,
    "this_month": 5210,
    "daily": [
      {
        "date": "2026-10-01",
        "downloads": 190
      },
      {
        "date": "2026-10-02",
        "downloads": 205
      },
      {
        "date": "2026-10-03",
        "downloads": 198
      }
    ],
    "range_total": 593
  },
  "isError": false
}
```

## Get episode stats

MCP tool: `libsyn_get_episode_stats`

Access: read.

Returns downloads for one episode in its first 7, 30 and 90 days and all time, so episodes of different age compare fairly. daily lists downloads per day for the range you choose and range_total adds them up. Read only.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `episode_id` | string | yes | Episode ID from list_episodes. |
| `start_date` | date | no | First day of the range. Default: 30 days ago. |
| `end_date` | date | no | Last day of the range. Default: today. |
| `metric` | enum | no | iab or unique downloads. Default: iab. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "libsyn_get_episode_stats",
    "arguments": {
      "episode_id": "episode_8c41d2"
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "episode_id": "38415502",
    "title": "Pricing your first product",
    "metric": "iab",
    "first_7_days": 1840,
    "first_30_days": 4215,
    "first_90_days": 6120,
    "all_time": 7310,
    "daily": [
      {
        "date": "2026-09-01",
        "downloads": 212
      },
      {
        "date": "2026-09-02",
        "downloads": 198
      },
      {
        "date": "2026-09-03",
        "downloads": 187
      }
    ],
    "range_total": 597
  },
  "isError": false
}
```

## Get downloads breakdown

MCP tool: `libsyn_get_downloads_breakdown`

Access: read.

Splits a show's downloads for a date range by country, listening app (user_agent) or publishing destination, biggest first. total_downloads is the sum of the rows. It needs the Advanced Plan or higher; on other plans the call fails with a plan error. Read only.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `show_id` | string | no | Show ID from list_shows. Default: your only or first show. |
| `by` | enum | yes | country, user_agent or destination. |
| `start_date` | date | no | First day of the range. Default: 30 days ago. |
| `end_date` | date | no | Last day of the range. Default: today. |
| `metric` | enum | no | iab or unique downloads. Default: iab. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "libsyn_get_downloads_breakdown",
    "arguments": {
      "by": "country",
      "start_date": "2026-09-01",
      "end_date": "2026-09-30",
      "metric": "iab"
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "show_id": "412907",
    "by": "country",
    "metric": "iab",
    "rows": [
      {
        "key": "United States",
        "downloads": 9120
      },
      {
        "key": "Canada",
        "downloads": 2210
      },
      {
        "key": "United Kingdom",
        "downloads": 1875
      },
      {
        "key": "Germany",
        "downloads": 940
      },
      {
        "key": "Other",
        "downloads": 3855
      }
    ],
    "total_downloads": 18000
  },
  "isError": false
}
```

## Export stats report

MCP tool: `libsyn_export_stats_report`

Access: read.

Runs the Stats Export for a show and returns a link to a zip with one file per report you ask for. Formats are csv, xlsb and pdf. It needs the Advanced Plan or higher. It only reads, and the link is for you to fetch or pass to the next step of your automation.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `show_id` | string | no | Show ID from list_shows. Default: your only or first show. |
| `reports` | string[] | yes | Any of total_downloads, by_episodes, by_country, by_destination, by_user_agent. |
| `range` | enum | no | last_30_days, last_60_days, last_90_days or all_time. Default: last_30_days. |
| `format` | enum | no | csv, xlsb or pdf. Default: csv. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "libsyn_export_stats_report",
    "arguments": {
      "reports": [
        "reports"
      ]
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "show_id": "412907",
    "status": "ready",
    "range": "last_30_days",
    "format": "csv",
    "files": [
      "total_downloads.csv",
      "by_country.csv"
    ],
    "download_url": "https://example.com/exports/412907-last_30_days.zip"
  },
  "isError": false
}
```

## Upload media file

MCP tool: `libsyn_upload_media`

Access: write.

Fetches a file from a public or signed URL and adds it to the media library of one show. It accepts mp3, m4a, mp4, m4v, ogg and pdf. The file name must be unique in your show. Nothing is published and nobody is notified, so it runs without asking; attach the returned media_file_id to a draft with create_episode.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `show_id` | string | no | Show ID from list_shows. Default: your only or first show. |
| `file_url` | string | yes | Public or signed URL of an mp3, m4a, mp4, m4v, ogg or pdf file. |
| `file_name` | string | no | Must be unique in your show. Default: name from the URL. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "libsyn_upload_media",
    "arguments": {
      "file_url": "https://example.com"
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "media_file_id": "f_88120",
    "file_name": "ep-142.mp3",
    "status": "uploaded"
  },
  "isError": false
}
```

## Create episode draft

MCP tool: `libsyn_create_episode`

Access: write.

Saves a new episode as a Draft with its title, show notes and details. Show notes are HTML or Markdown; Apple Podcasts shows up to 4,000 characters. Nothing reaches listeners until schedule_episode or publish_episode, so this call runs without asking and you can delete the draft in the dashboard.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `show_id` | string | no | Show ID from list_shows. Default: your only or first show. |
| `title` | string | yes | Episode title, shown in podcast apps. |
| `description` | string | yes | Show notes, HTML or Markdown. Apple Podcasts shows up to 4,000 characters. |
| `media_file_id` | string | no | File from upload_media. |
| `season_number` | integer | no | Season number. |
| `episode_number` | integer | no | Episode number. |
| `episode_type` | enum | no | full, trailer or bonus. Default: full. |
| `rating` | enum | no | clean or explicit. Default: show setting. |
| `author` | string | no | Episode author. |
| `tags` | string[] | no | Episode tags. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "libsyn_create_episode",
    "arguments": {
      "title": "title",
      "description": "description"
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "episode_id": "38415502",
    "status": "draft",
    "title": "Pricing your first product",
    "season_number": 3,
    "episode_number": 12,
    "media_file_id": "f_88120"
  },
  "isError": false
}
```

## Update episode

MCP tool: `libsyn_update_episode`

Access: write. Confirm: waits for the user's OK before it runs.

Changes the fields you pass and leaves the rest. On a published episode the RSS feed updates, so podcast apps show the change. Read the current text with get_episode first if you add to it. By default you confirm each call; you can switch that off for this tool.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `episode_id` | string | yes | Episode ID from list_episodes. |
| `fields` | object | yes | Any of title, description, season_number, episode_number, episode_type, rating, author, tags. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "libsyn_update_episode",
    "arguments": {
      "episode_id": "38201877",
      "fields": {
        "description": "<p>How to land your first ten customers.</p><p>This episode is supported by Acme: <a href=\"https://acme.example/podcast\">acme.example/podcast</a></p>"
      }
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "episode_id": "38415502",
    "status": "scheduled",
    "updated_fields": [
      "description"
    ]
  },
  "isError": false
}
```

## Bulk edit episodes

MCP tool: `libsyn_bulk_edit_episodes`

Access: write. Confirm: waits for the user's OK before it runs.

Sets the author and season on the episodes you list and can number them in the order you pass them: top_to_bottom numbers from the first ID, bottom_to_top from the last. The RSS feed refreshes after the change. It returns every episode with its new number. By default you confirm each call; you can switch that off for this tool.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `episode_ids` | string[] | yes | Episodes to edit. |
| `author` | string | no | New author for all of them. |
| `season_number` | integer | no | New season for all of them. |
| `numbering` | enum | no | none, top_to_bottom or bottom_to_top. Default: none. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "libsyn_bulk_edit_episodes",
    "arguments": {
      "episode_ids": [
        "episode ids"
      ]
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "updated": 3,
    "season_number": 3,
    "numbering": "bottom_to_top",
    "episodes": [
      {
        "episode_id": "38415502",
        "episode_number": 3
      },
      {
        "episode_id": "38201877",
        "episode_number": 2
      },
      {
        "episode_id": "38009640",
        "episode_number": 1
      }
    ]
  },
  "isError": false
}
```

## Upload transcript

MCP tool: `libsyn_upload_transcript`

Access: write. Confirm: waits for the user's OK before it runs.

Fetches an .srt or .vtt file from a URL and attaches it to one episode. Libsyn adds the transcript to the feed for Apple Podcasts and other apps, so it can reach listeners. By default you confirm each call; you can switch that off for this tool.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `episode_id` | string | yes | Episode ID from list_episodes. |
| `file_url` | string | yes | URL of an .srt or .vtt file. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "libsyn_upload_transcript",
    "arguments": {
      "episode_id": "38415502",
      "file_url": "https://files.example.com/transcripts/ep-142.vtt"
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "episode_id": "38415502",
    "transcript": {
      "format": "vtt",
      "status": "attached"
    }
  },
  "isError": false
}
```

## Schedule episode

MCP tool: `libsyn_schedule_episode`

Access: write. Confirm: waits for the user's OK before it runs.

Sets a release time for a draft. At that time Libsyn publishes it to every destination the show is connected to, such as Apple Podcasts, Spotify and YouTube. release_at needs a time zone. By default you confirm each call; you can switch that off for this tool.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `episode_id` | string | yes | Episode ID from list_episodes. |
| `release_at` | datetime | yes | ISO 8601 with time zone. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "libsyn_schedule_episode",
    "arguments": {
      "episode_id": "38415502",
      "release_at": "2026-10-15T06:00:00-04:00"
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "episode_id": "38415502",
    "status": "scheduled",
    "title": "Pricing your first product",
    "release_at": "2026-10-15T06:00:00-04:00",
    "url": "https://yourname.libsyn.com/pricing-your-first-product"
  },
  "isError": false
}
```

## Publish episode

MCP tool: `libsyn_publish_episode`

Access: write. Confirm: waits for the user's OK before it runs.

Publishes a draft at once to every destination the show is connected to. Listeners can see it as soon as their apps refresh the feed. To release later, use schedule_episode. By default you confirm each call; you can switch that off for this tool.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `episode_id` | string | yes | Episode ID from list_episodes. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "libsyn_publish_episode",
    "arguments": {
      "episode_id": "episode_8c41d2"
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "episode_id": "38415502",
    "status": "published",
    "title": "Pricing your first product",
    "url": "https://yourname.libsyn.com/pricing-your-first-product"
  },
  "isError": false
}
```