Docs & Usage Guide

🎙️ Podbean MCP Server 🎧

An MCP server for managing your podcast through the Podbean API.

🎉 Overview

This MCP server connects any MCP-compatible AI assistant to the Podbean API. Whether you're using Cline (the IDE MCP Client), Claude Desktop, or any other MCP client, you can now manage your podcasts, episodes, and analytics through natural conversation!

✨ Features

🔐 Authentication

Client credentials authentication for managing your own podcasts
OAuth flow for third-party access (when needed)
Token management for multiple podcasts - juggle them all!

🎙️ Podcast Management

List all your awesome podcasts in one place
Get the nitty-gritty details about your shows
Peek at your stats and analytics (who's listening?)
Browse podcast categories to find your niche

📝 Episode Management

See all episodes for your podcast at a glance
Dig into the details of any episode
Publish new episodes with ease (no more complex forms!)
Update existing episodes when you need a tweak
Delete episodes that didn't quite hit the mark

📁 File Management (Limited)

Get authorization for file uploads to Podbean (presigned URLs)
Note: Due to STDIO protocol limitations, this server cannot directly upload files
The server provides the necessary authorization and file keys, but actual file uploads must be handled externally

📊 Analytics

Check out how many downloads your podcast is getting
Track your daily listener counts (watching them grow!)
See how users are interacting with your content

🌐 Public Podcast Access

Access public podcast data through oEmbed
Get the scoop on any public episode out there

🧰 Prerequisites

Python 3.10 or higher (time to upgrade if you haven't already!)
A Podbean account with API access (free or paid - they're all welcome)
Podbean API credentials (Client ID and Secret - your magical keys to the kingdom)

🚀 Installation

Installing via Smithery

To install Podbean Podcast Manager for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install @amurshak/podbeanmcp --client claude

Grab the code:

git clone <repository-url>
cd PodbeanMCP

Set up a virtual environment using the super-speedy uv tool:

uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

Install the package and its dependencies:
```
# Using uv (faster)
uv pip install -e .
```
Or if you prefer traditional pip:
```
pip install -e .
```
This will install all dependencies from the pyproject.toml file, including:
- mcp[cli] (MCP SDK)
- httpx (for API requests)
- python-dotenv (for environment variables)
- pydantic (for data validation)

Create a .env file with your secret Podbean powers:

PODBEAN_CLIENT_ID=your_client_id
PODBEAN_CLIENT_SECRET=your_client_secret

📝 Configuring in cline_mcp_settings.json

The recommended way to use this MCP server is to configure it directly in your cline_mcp_settings.json file. This allows the Cline IDE MCP Client to automatically start the server when needed.

Locate your cline_mcp_settings.json file. This file is used by Cline IDE to configure MCP servers. Refer to the Cline IDE documentation for the exact location of this file on your system.
Add the Podbean MCP server configuration to the "mcpServers" object:

{
  "mcpServers": {
    "Podbean MCP": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp[cli]",
        "mcp",
        "run",
        "/full/path/to/PodbeanMCP/server.py"
      ],
      "env": {
        "PODBEAN_CLIENT_ID": "your_client_id",
        "PODBEAN_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

Customize the configuration:
- Replace /full/path/to/PodbeanMCP/server.py with the absolute path to your server.py file
- Replace your_client_id and your_client_secret with your Podbean API credentials from your .env file
- If you're not using uv, adjust the command and args accordingly
Save the file and restart Cline IDE

Important Note: You do not need to manually run the server with python server.py when using this configuration. Cline IDE will automatically start the server when needed and Claude (the AI) will be able to access it.

Example with Multiple Servers

If you already have other MCP servers in your config, simply add the Podbean MCP server as a new entry:

{
  "mcpServers": {
    "Some Other MCP": {
      "command": "...",
      "args": [
        "..."
      ]
    },
    "Podbean MCP": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp[cli]",
        "mcp",
        "run",
        "/full/path/to/PodbeanMCP/server.py"
      ],
      "env": {
        "PODBEAN_CLIENT_ID": "your_client_id",
        "PODBEAN_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

🧪 Testing Your Installation

After configuring the MCP server in your cline_mcp_settings.json file, you can test if it's working properly by asking Claude to use one of the Podbean MCP tools:

Authenticate with Podbean:

Can you authenticate with my Podbean account using the Podbean MCP server?

List your podcasts:

Can you list my podcasts using the Podbean MCP server?

Get episodes for a specific podcast:

Can you get the episodes for my podcast with ID "your_podcast_id" using the Podbean MCP server?

If Claude successfully executes these commands and returns the expected results, your Podbean MCP server is working correctly!

🔧 Available Tools

🔑 Authentication Tools

authenticate_with_podbean(): Get your VIP backstage pass to Podbean
get_podcast_tokens(): Collect tokens for all your podcasts like Pokémon
get_podcast_token(podcast_id): Grab a token for just that special podcast

🎙️ Podcast Tools

list_podcasts_tool(): See your podcast empire at a glance
get_podcast_info(): Get the 411 on your podcast
get_podcast_stats(podcast_id, start_date, end_date, period, episode_id): Numbers, charts, and bragging rights!
get_daily_listeners(podcast_id, month): Track your growing audience day by day
browse_podcast_categories(): Explore the podcast universe by category

🎧 Episode Tools

get_podcast_episodes_tool(podcast_id): Round up all episodes from your show
get_episode_details_tool(episode_id): Zoom in on a specific episode
publish_episode(podcast_id, title, content, ...): Release your voice to the world!
update_episode(episode_id, podcast_id, ...): Tweak that episode to perfection
delete_episode(episode_id, podcast_id, delete_media): Oops! That one needs to go...

💾 File Authorization Tools (Limited)

authorize_file_upload(podcast_id, filename, filesize, content_type): Get permission to upload files
upload_file_to_podbean(presigned_url, file_path, content_type, file_key): Note: This is a placeholder function that simulates file uploads but doesn't actually transfer files due to STDIO protocol limitations

🌐 Public Access Tools

get_oembed_data(url): Get embeddable goodies for any Podbean URL
get_public_episode_info(episode_url): Snoop on any public episode (legally, of course!)

🔗 OAuth Tools (for Third-Party Access)

generate_oauth_url(redirect_uri, scope, state): Create a magic login link
exchange_oauth_code(code, redirect_uri): Trade your code for a shiny token
refresh_oauth_token(refresh_token): Renew your expired token - no waiting in line!

📚 Available Resources

podbean://auth: Your authentication treasure chest
podbean://podcast/{podcast_id}: Episode collection for your podcast
podbean://episode/{episode_id}: All the juicy details about an episode
podbean://upload/authorize: Your upload permission slip (but not actual uploads)
podbean://categories: The podcast category encyclopedia
podbean://public/oembed: Embed-friendly data for any Podbean URL
podbean://oauth/authorize: Your OAuth permission gateway

💬 Available Prompts

podcast_summary(podcast_id): "Hey AI, can you summarize my podcast?"
episode_transcript(episode_id): "Turn my ramblings into readable text, please!"

💬 Example Usage with Any MCP Client

Here are some fun ways to chat with your AI assistant using this MCP server:

Get the VIP pass:

Hey, can you authenticate with my Podbean account and show me my podcast collection?

Round up the episodes:

I'm feeling nostalgic! Show me all the episodes from my "Cooking with Code" podcast.

Share your brilliance with the world:

I'm ready to drop a new episode! It's called "AI in Podcasting" and it's all about how AI is making podcasting easier and more fun. Can you help me publish it?

Check if anyone's listening 👂:

How's my podcast doing? Can you show me the download stats from last week?

🛠️ Error Handling

We've got your back when things go sideways! This server comes with super-friendly error handling:

Authentication hiccups? We'll guide you through fixing them 🔧
API giving you trouble? We'll tell you exactly what went wrong 🚨
Tried something that doesn't compute? We'll let you know before it breaks 🤓
Detailed error messages that actually make sense to humans! 😮‍💨

🚧 Limitations

File Uploads: Due to STDIO protocol limitations, this server cannot directly upload files to Podbean. It can obtain the necessary authorization (presigned URLs) and file keys, but the actual file transfer must be handled by external tools or processes.
Some fancy features might need a paid Podbean subscription 💳
Podbean has rate limits, so don't go too wild with the requests 🚀
We can't make your podcast content go viral (that's still on you!) 🌟

👩‍💻 Contributing

Got ideas to make this even better? We'd love your help! Fork, code, and send us a Pull Request. Let's make podcast management even more awesome together! 🤝

📃 License

[Insert your favorite license here - keep it open source if you can!]

👏 Acknowledgments

The amazing folks behind the Podbean API docs 📖
The wizards who created the MCP SDK 🧙‍♂️
You, for using this tool to make awesome podcasts! 🎉

Podbean