# Pocket Casts MCP Server

An MCP (Model Context Protocol) server that connects to the Pocket Casts podcast app, allowing AI assistants to search, browse, and manage your podcast library.

> **Note:** This uses the unofficial Pocket Casts API. There is no official public API — this server relies on reverse-engineered endpoints used by community projects.

## Prerequisites

- Node.js 18+
- A Pocket Casts account (email & password)

## Installation

### Remote (npx — no clone required)

Run the server directly without installing anything locally:

```bash
npx pocketcasts-mcp
```

#### Claude Desktop

Add to your config file:

- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "pocketcasts": {
      "command": "npx",
      "args": ["-y", "pocketcasts-mcp"],
      "env": {
        "POCKETCASTS_EMAIL": "your@email.com",
        "POCKETCASTS_PASSWORD": "your-password"
      }
    }
  }
}
```

#### Claude Code

```bash
claude mcp add pocketcasts \
  -e POCKETCASTS_EMAIL=your@email.com \
  -e POCKETCASTS_PASSWORD=your-password \
  -s user \
  -- npx -y pocketcasts-mcp
```

The `-s user` flag makes the server available across all your projects. Omit it to scope to the current project only.

#### Global install (alternative)

Install once, then reference the command directly:

```bash
npm install -g pocketcasts-mcp
```

Then use `pocketcasts-mcp` as the command instead of `npx -y pocketcasts-mcp` in the configs above.

---

### Local (from source)

Clone and build the server yourself:

```bash
git clone https://github.com/essoen/PocketCasts-mcp.git
cd PocketCasts-mcp
npm install
npm run build
```

#### Claude Desktop

```json
{
  "mcpServers": {
    "pocketcasts": {
      "command": "node",
      "args": ["/absolute/path/to/PocketCasts-mcp/dist/index.js"],
      "env": {
        "POCKETCASTS_EMAIL": "your@email.com",
        "POCKETCASTS_PASSWORD": "your-password"
      }
    }
  }
}
```

#### Claude Code

```bash
claude mcp add pocketcasts \
  -e POCKETCASTS_EMAIL=your@email.com \
  -e POCKETCASTS_PASSWORD=your-password \
  -s user \
  -- node /absolute/path/to/PocketCasts-mcp/dist/index.js
```

#### Cursor / VS Code

Add to `.cursor/mcp.json` or `.vscode/mcp.json` in your project:

```json
{
  "mcpServers": {
    "pocketcasts": {
      "command": "node",
      "args": ["/absolute/path/to/PocketCasts-mcp/dist/index.js"],
      "env": {
        "POCKETCASTS_EMAIL": "your@email.com",
        "POCKETCASTS_PASSWORD": "your-password"
      }
    }
  }
}
```

Or with npx (no local clone needed):

```json
{
  "mcpServers": {
    "pocketcasts": {
      "command": "npx",
      "args": ["-y", "pocketcasts-mcp"],
      "env": {
        "POCKETCASTS_EMAIL": "your@email.com",
        "POCKETCASTS_PASSWORD": "your-password"
      }
    }
  }
}
```

---

## Configuration

The server requires two environment variables:

| Variable | Description |
|----------|-------------|
| `POCKETCASTS_EMAIL` | Your Pocket Casts account email |
| `POCKETCASTS_PASSWORD` | Your Pocket Casts account password |

These can be set via:
- The `env` block in your MCP client config (recommended)
- Your shell profile (`~/.bashrc`, `~/.zshrc`, etc.)
- A `.env` file in your project (if your MCP client supports it)

> **Security:** Never commit files containing your credentials to version control. If using a `.env` file, ensure it is listed in `.gitignore`. Avoid storing passwords in config files that may be synced or backed up to cloud services.

## Available Tools

### Discovery
| Tool | Description |
|------|-------------|
| `search_podcasts` | Search for podcasts by keyword or title |
| `get_top_charts` | Get top-ranked podcasts |
| `get_trending` | Get currently trending podcasts |
| `get_featured` | Get featured podcasts |

### Library
| Tool | Description |
|------|-------------|
| `get_subscriptions` | List all subscribed podcasts |

### Episodes
| Tool | Description |
|------|-------------|
| `get_podcast_episodes` | List episodes for a podcast (sorted newest or oldest) |
| `get_episode_notes` | Get show notes for an episode |
| `get_new_releases` | Get new episodes from subscriptions |
| `get_in_progress` | Get partially-listened episodes |
| `get_starred` | Get starred/favorited episodes |
| `get_history` | Get listening history (most recent 100) |

### Playback Management
| Tool | Description |
|------|-------------|
| `update_playing_status` | Mark episode as unplayed, in_progress, or completed |
| `update_played_position` | Set playback resume position (in seconds) |
| `update_starred` | Star or unstar an episode |

## Development

```bash
git clone https://github.com/essoen/PocketCasts-mcp.git
cd PocketCasts-mcp
npm install
npm run build
npm start
```

## API Reference

This server uses the unofficial Pocket Casts API at `api.pocketcasts.com`. Endpoints were reverse-engineered by the community. See [furgoose/Pocket-Casts](https://github.com/furgoose/Pocket-Casts) for the original documentation.

## License

MIT