# conorbronsdon/op3-mcp [Health: Active] **Category:** 🎙️ Podcasts **Repository:** https://github.com/conorbronsdon/op3-mcp **GitHub Stars:** 1 **npm Downloads (last month):** 242 **Views:** 2 **Installs:** 0 **Upvotes:** 0 **Directory Page:** https://allmcps.com/mcp/conorbronsdon-op3-mcp ## Description Podcast analytics from OP3, the Open Podcast Prefix Project: downloads over time, listener geography, app share, and per-episode breakdowns. Read-only by design. ## Tools Capabilities this server exposes over MCP: - **op3_get_show** — Look up a podcast show on OP3 and get its UUID, title, podcast GUID, and stats page URL. Pass a show UUID, a podcast:guid, or a base64-encoded feed URL. This is the entry point: most other tools need the show UUID this returns. Set include_episodes to also list episodes (id, title, pubdate). - **op3_show_downloads** — Get a show's recent download summary from OP3: monthly downloads, a week-by-week breakdown, and the average weekly downloads. Use this for 'how many downloads does my show get' questions. Needs a show UUID (from op3_get_show). - **op3_episode_downloads** — Get per-episode download counts for a show from OP3: for each recent episode, downloads in the first 1/3/7/30 days after publish and all-time. Good for comparing how episodes perform. Needs a show UUID. Use limit to cap how many episodes come back. - **op3_top_apps** — Get the top podcast apps and players downloading a show, from OP3, over the last three calendar months. Returns each app with its download count and percent share. Answers 'what apps do my listeners use'. Needs a show UUID. - **op3_top_countries** — Get the top listener countries (or regions) for a show. NOTE: OP3 has no native geography query, so this counts raw download records and aggregates by country client-side. It is a representative sample, not an exact lifetime total. OP3 returns raw records oldest-first, so to keep the sample recent this tool defaults to the last `window_days` days (90) when you do not pass an explicit start. Each result has a download count and percent share. Needs a show UUID. Keep max_records modest to stay fast and within rate limits. - **op3_downloads_timeseries** — Fetch raw download records for a show from OP3 over a date range. Returns individual download events (time, country, app, device). This is the low-level feed behind the other tools. Use it when you need to filter by episode or a specific date window. Keep limit low (records are verbose). For totals or geography summaries, prefer op3_show_downloads / op3_top_countries. ## Claude Desktop Quick Installation Install path detected from listing signals. Uses `npx` (confidence: high): ```json "mcpServers": { "op3-mcp": { "command": "npx", "args": ["-y","@conorbronsdon/op3-mcp"], "env": { "OP3_API_TOKEN": "" } } } ``` **Requires environment variables:** `OP3_API_TOKEN` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for). ## Documentation & README
# op3-mcp Podcast analytics for AI agents through OP3: downloads over time, listener geography, apps, and per-episode breakdowns. Read-only. [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](LICENSE) [![npm version](https://img.shields.io/npm/v/@conorbronsdon/op3-mcp?style=flat-square)](https://www.npmjs.com/package/@conorbronsdon/op3-mcp) [![Node](https://img.shields.io/badge/Node-18+-339933?style=flat-square&logo=node.js&logoColor=white)](https://nodejs.org/) [![Podcast](https://img.shields.io/badge/Podcast-Chain_of_Thought-purple?style=flat-square)](https://chainofthought.show/?utm_source=github&utm_medium=referral&utm_campaign=repo-readme&utm_content=op3-mcp) [![X](https://img.shields.io/badge/X-@ConorBronsdon-black?style=flat-square&logo=x)](https://x.com/ConorBronsdon) Demo: an agent calls the op3_show_downloads tool and gets monthly and weekly download counts back (sample data)
--- An MCP server for [OP3](https://op3.dev), the Open Podcast Prefix Project. It gives AI assistants podcast analytics that most hosting APIs do not expose: downloads over time, listener geography, the apps people listen in, and per-episode breakdowns. **Read-only by design.** OP3 is an analytics service. This server only reads data. It cannot change anything, so it is safe to give an agent. **Why this exists.** Most podcast hosts expose almost nothing through their API. Transistor's API, for example, returns download counts and not much else: no geography, no app share, no per-episode recency curve. OP3 has all of that, because it logs each download at the redirect. This server puts that data in front of an agent. op3-mcp MCP server ## What is OP3? OP3 is a free, open analytics prefix for podcasts. You add `https://op3.dev/e/` in front of your enclosure URLs, and OP3 logs each download before redirecting to your real audio file. It then reports downloads, geography, and app share. Stats pages are public; the API needs a token. See https://op3.dev for details. If your feed does not use the OP3 prefix yet, OP3 has no data for it. See "Adding the OP3 prefix" below. ## Tools | Tool | What it returns | OP3 endpoint | |------|-----------------|--------------| | `op3_get_show` | Show UUID, title, podcast GUID, stats page URL, optional episode list | `GET /shows/{showUuidOrPodcastGuidOrFeedUrlBase64}` | | `op3_show_downloads` | Monthly downloads, weekly breakdown, weekly average | `GET /queries/show-download-counts` | | `op3_episode_downloads` | Per-episode downloads at 1/3/7/30 days and all-time | `GET /queries/episode-download-counts` | | `op3_top_apps` | Top apps/players by download share, last 3 calendar months | `GET /queries/top-apps-for-show` | | `op3_top_countries` | Top listener countries or regions (computed from raw records) | `GET /downloads/show/{showUuid}` | | `op3_downloads_timeseries` | Raw download events over a date range (time, country, app, device) | `GET /downloads/show/{showUuid}` | Most tools need a show UUID. Start with `op3_get_show` to turn a feed URL or podcast GUID into a UUID. Every list tool takes a `limit` and defaults it low (10) to keep responses small. Agents pay tokens per response. ## Setup ### 1. Get a token 1. Go to https://op3.dev and sign in. 2. Open your API token page and copy the token. 3. For trying things out, OP3 also publishes a shared preview token, `preview07ce`, which works against public shows. ### 2. Find your show UUID If you know your feed URL or podcast GUID, ask the assistant to run `op3_get_show` with it and it will return your UUID. You can also read the UUID from your show's OP3 stats page URL: `https://op3.dev/show/{showUuid}`. ### 3. Configure your MCP client #### Claude Code Add to your `.mcp.json`: ```json { "mcpServers": { "op3": { "command": "npx", "args": ["-y", "@conorbronsdon/op3-mcp"], "env": { "OP3_API_TOKEN": "your-op3-token" } } } } ``` #### Claude Desktop Add to your `claude_desktop_config.json`: ```json { "mcpServers": { "op3": { "command": "npx", "args": ["-y", "@conorbronsdon/op3-mcp"], "env": { "OP3_API_TOKEN": "your-op3-token" } } } } ``` ### 4. Verify Ask your assistant: "Look up my show on OP3" with your feed URL, then "How many downloads did it get last month?" ## Adding the OP3 prefix (if you are not on OP3 yet) OP3 only has data once downloads route through its prefix. To start: 1. In your podcast host, prepend `https://op3.dev/e/` to your episode audio URLs. Many hosts (Transistor, Buzzsprout, and others) have a one-click OP3 toggle. Check your host's settings for an "OP3" or "analytics prefix" option. 2. New downloads will start being logged. Historical downloads from before you added the prefix are not backfilled. 3. Find your show on https://op3.dev and note its stats page URL, which contains your show UUID. ## Limitations Read these so you know what the numbers mean. - **Geography is a computed sample, not an exact total.** OP3 has no country-level aggregate endpoint. `op3_top_countries` pulls raw download records and counts them by country on the client side. The result is representative, not a precise lifetime figure. OP3 returns raw records oldest-first, so the tool defaults to the **last 90 days** (`window_days`) when you do not pass an explicit `start` — otherwise the sample would be the show's *oldest* downloads, not recent listeners. Within the window, records are still sampled oldest-first, so on a high-volume show a `max_records` sample skews toward the start of the window; the response includes `sampleHitCap` so you can tell when the window held more records than were sampled. Raise `max_records` (cap 20000) for a larger, more representative sample at the cost of speed and rate-limit headroom. - **No device breakdown tool.** OP3's raw records include a `deviceType` and `deviceName`, but there is no aggregate device query. You can see per-record device info via `op3_downloads_timeseries`. App share is available and exposed through `op3_top_apps`. - **Top apps covers the last three calendar months only.** That window is fixed by OP3, not configurable. - **Data starts when the prefix was added.** OP3 cannot report on downloads that never went through its redirect. - **Bots are excluded by default** in OP3's download queries, which is usually what you want. - **Rate limits are not publicly documented.** Keep `limit` and `max_records` modest. The server surfaces a clear error on HTTP 429. ### Typed errors API failures are mapped to a typed error hierarchy (`OP3APIError` base, with `AuthError`, `RateLimitError`, `NotFoundError`, `ValidationError`, and `ServerError` subclasses keyed off HTTP status) in `src/errors.ts`: - `AuthError` (401/403) — the OP3 token is missing or invalid. - `RateLimitError` (429) — too many requests against the OP3 API. - `NotFoundError` (404) — the show, feed, or resource doesn't exist (or isn't on OP3 yet). - `ValidationError` (400) — a malformed or invalid request parameter. - `ServerError` (5xx) — a failure on OP3's side; the specific status (500, 502, 503, ...) is preserved in the message. - `OP3APIError` — the base class, used as a fallback for unmapped status codes or network failures. Every tool call still returns the same `isError: true` response shape on failure — the typed hierarchy just makes the message specific to what went wrong instead of a single generic "API error" string. ## Development ```bash git clone https://github.com/conorbronsdon/op3-mcp.git cd op3-mcp npm install npm run build npm test ``` Run locally: ```bash OP3_API_TOKEN=your-token npm start ``` Tests mock `fetch` and make no network calls. ## Contributing Issues and pull requests are welcome. If an OP3 endpoint changes shape, or there is an aggregate query worth wrapping as a tool, open an issue describing what you want and the OP3 endpoint it maps to. Keep the read-only contract: this server reports analytics, it does not change anything. ## About Built and maintained by [Conor Bronsdon](https://github.com/conorbronsdon). I host the [Chain of Thought](https://chainofthought.show/?utm_source=github&utm_medium=referral&utm_campaign=repo-readme&utm_content=op3-mcp) podcast, which covers AI infrastructure, developer tools, and how practitioners actually use this stuff. I built this to pull honest listener analytics into the agent workflows that run the show. Companion tools: - [podcast-benchmark](https://github.com/conorbronsdon/podcast-benchmark): benchmark your show against peers on public signals. The public-data complement to your own private OP3 analytics here. - [Transistor-MCP](https://github.com/conorbronsdon/Transistor-MCP): the Transistor.fm MCP server. Episodes, transcripts, and the download counts that OP3 fills out with geography and apps. - [substack-mcp](https://github.com/conorbronsdon/substack-mcp): read posts and manage drafts on Substack, safe for agent workflows. - [podcastindex-mcp](https://github.com/conorbronsdon/podcastindex-mcp): the Podcast Index MCP server, search by person or topic, trending shows, feed health. - [ai-tools-for-creators](https://github.com/conorbronsdon/ai-tools-for-creators): a curated list of AI skills and MCP servers for people who ship ideas for a living. More at [chainofthought.show](https://chainofthought.show/?utm_source=github&utm_medium=referral&utm_campaign=repo-readme&utm_content=op3-mcp) and on [X](https://x.com/ConorBronsdon). --- ## Disclaimer *This is an independent personal project, not affiliated with, sponsored by, or endorsed by any company. All views expressed are my own.* ## License MIT