podcastindex-mcp

<div align="center">

# Podcast Index MCP Server

Connect Claude to the Podcast Index API. Search podcasts, track appearances, monitor trends.

[![GitHub stars](https://img.shields.io/github/stars/conorbronsdon/podcastindex-mcp?style=social)](https://github.com/conorbronsdon/podcastindex-mcp/stargazers)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](LICENSE)
[![npm version](https://img.shields.io/npm/v/podcastindex-mcp?style=flat-square)](https://www.npmjs.com/package/podcastindex-mcp)
[![Podcast](https://img.shields.io/badge/Podcast-Chain_of_Thought-purple?style=flat-square)](https://chainofthought.show)
[![X](https://img.shields.io/badge/X-@ConorBronsdon-black?style=flat-square&logo=x)](https://x.com/ConorBronsdon)

</div>

---

![Demo: search_by_person tool call and response](docs/demo.gif)

The results shown in the demo above are sample data, not real Podcast Index responses.

## About

Built and maintained by [Conor Bronsdon](https://github.com/conorbronsdon) for the [Chain of Thought](https://chainofthought.show) podcast production workflow, where it surfaces guest appearances and checks feed health during research. Conor hosts Chain of Thought, a show about AI infrastructure and how practitioners actually build with it. More tools for creators live in [ai-tools-for-creators](https://github.com/conorbronsdon/ai-tools-for-creators). Find Conor on X at [@ConorBronsdon](https://x.com/ConorBronsdon).

**Sibling MCP servers:**
- [Transistor-MCP](https://github.com/conorbronsdon/Transistor-MCP): manage podcast episodes, analytics, and transcripts on Transistor.fm
- [substack-mcp](https://github.com/conorbronsdon/substack-mcp): read posts and manage Substack drafts

## Prerequisites

- Node.js 18+
- Free Podcast Index API credentials -- get them at [api.podcastindex.org](https://api.podcastindex.org/)

## Installation

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

## Configuration

### Claude Desktop

Add to your Claude Desktop config (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "podcastindex": {
      "command": "node",
      "args": ["/path/to/podcastindex-mcp/build/index.js"],
      "env": {
        "PODCASTINDEX_API_KEY": "your-api-key",
        "PODCASTINDEX_API_SECRET": "your-api-secret"
      }
    }
  }
}
```

### Claude Code

Add to your project's `.mcp.json`:

```json
{
  "mcpServers": {
    "podcastindex": {
      "command": "node",
      "args": ["/path/to/podcastindex-mcp/build/index.js"],
      "env": {
        "PODCASTINDEX_API_KEY": "your-api-key",
        "PODCASTINDEX_API_SECRET": "your-api-secret"
      }
    }
  }
}
```

## Tools

This server is entirely read-only: every tool declares the MCP [tool annotation](https://modelcontextprotocol.io/docs/concepts/tools#tool-annotations) `readOnlyHint: true`, so clients know no call mutates anything and can skip write-consent prompts.

| Tool | Description |
|------|-------------|
| `search_by_person` | Search for episodes where a person appeared as host or guest. Returns matches across all indexed podcasts. |
| `search_by_term` | Full-text search across all podcasts by topic, show name, or keyword. |
| `podcast_by_feed_url` | Look up a podcast by RSS feed URL. Returns feed ID, iTunes ID, categories, last update, and feed health. |
| `podcast_by_feed_id` | Look up a podcast by its Podcast Index feed ID. Returns full metadata. |
| `trending_podcasts` | Get currently trending podcasts, with optional language and category filters. |
| `episodes_by_feed_id` | Get episodes for a specific podcast by feed ID. |
| `recent_episodes` | Get the most recently published episodes across the entire index. |
| `categories_list` | Get the full list of Podcast Index categories and their IDs. |

## Example Prompts

Once configured, you can ask Claude things like:

- "Search Podcast Index for all episodes featuring Satya Nadella as a guest"
- "What are the trending technology podcasts right now?"
- "Look up the feed health for https://feeds.transistor.fm/chain-of-thought and list the last 5 episodes"

## Development

Build the project:

```bash
npm run build
```

Watch for changes during development:

```bash
npm run watch
```

### Adding a new tool

1. Add the API method to `src/api-client.ts`
2. Add type guard and argument types to `src/types.ts`
3. Add the tool definition and handler to `src/tool-handlers.ts`
4. Rebuild with `npm run build`

## Contributing

Issues and pull requests are welcome. If there is a Podcast Index endpoint you want exposed as a tool, open an issue describing the use case, or follow the steps above and open a PR. Bug reports should include the tool name and the arguments you passed.

---

## Disclaimer

*All views, opinions, and statements expressed on this account are solely my own and are made in my personal capacity. They do not reflect, and should not be construed as reflecting, the views, positions, or policies of Modular. This account is not affiliated with, authorized by, or endorsed by Modular in any way.*

## License

MIT