{ "markdown": "
\n\n# op3-mcp\n\nPodcast analytics for AI agents through OP3: downloads over time, listener geography, apps, and per-episode breakdowns. Read-only.\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](LICENSE)\n[![npm version](https://img.shields.io/npm/v/@conorbronsdon/op3-mcp?style=flat-square)](https://www.npmjs.com/package/@conorbronsdon/op3-mcp)\n[![Node](https://img.shields.io/badge/Node-18+-339933?style=flat-square&logo=node.js&logoColor=white)](https://nodejs.org/)\n[![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)\n[![X](https://img.shields.io/badge/X-@ConorBronsdon-black?style=flat-square&logo=x)](https://x.com/ConorBronsdon)\n\n\"Demo:\n\n
\n\n---\n\n\nAn 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.\n\n**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.\n\n**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.\n\n\n \"op3-mcp\n\n\n## What is OP3?\n\nOP3 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.\n\nIf your feed does not use the OP3 prefix yet, OP3 has no data for it. See \"Adding the OP3 prefix\" below.\n\n## Tools\n\n| Tool | What it returns | OP3 endpoint |\n|------|-----------------|--------------|\n| `op3_get_show` | Show UUID, title, podcast GUID, stats page URL, optional episode list | `GET /shows/{showUuidOrPodcastGuidOrFeedUrlBase64}` |\n| `op3_show_downloads` | Monthly downloads, weekly breakdown, weekly average | `GET /queries/show-download-counts` |\n| `op3_episode_downloads` | Per-episode downloads at 1/3/7/30 days and all-time | `GET /queries/episode-download-counts` |\n| `op3_top_apps` | Top apps/players by download share, last 3 calendar months | `GET /queries/top-apps-for-show` |\n| `op3_top_countries` | Top listener countries or regions (computed from raw records) | `GET /downloads/show/{showUuid}` |\n| `op3_downloads_timeseries` | Raw download events over a date range (time, country, app, device) | `GET /downloads/show/{showUuid}` |\n\nMost tools need a show UUID. Start with `op3_get_show` to turn a feed URL or podcast GUID into a UUID.\n\nEvery list tool takes a `limit` and defaults it low (10) to keep responses small. Agents pay tokens per response.\n\n## Setup\n\n### 1. Get a token\n\n1. Go to https://op3.dev and sign in.\n2. Open your API token page and copy the token.\n3. For trying things out, OP3 also publishes a shared preview token, `preview07ce`, which works against public shows.\n\n### 2. Find your show UUID\n\nIf 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}`.\n\n### 3. Configure your MCP client\n\n#### Claude Code\n\nAdd to your `.mcp.json`:\n\n```json\n{\n \"mcpServers\": {\n \"op3\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@conorbronsdon/op3-mcp\"],\n \"env\": {\n \"OP3_API_TOKEN\": \"your-op3-token\"\n }\n }\n }\n}\n```\n\n#### Claude Desktop\n\nAdd to your `claude_desktop_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"op3\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@conorbronsdon/op3-mcp\"],\n \"env\": {\n \"OP3_API_TOKEN\": \"your-op3-token\"\n }\n }\n }\n}\n```\n\n### 4. Verify\n\nAsk your assistant: \"Look up my show on OP3\" with your feed URL, then \"How many downloads did it get last month?\"\n\n## Adding the OP3 prefix (if you are not on OP3 yet)\n\nOP3 only has data once downloads route through its prefix. To start:\n\n1. 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.\n2. New downloads will start being logged. Historical downloads from before you added the prefix are not backfilled.\n3. Find your show on https://op3.dev and note its stats page URL, which contains your show UUID.\n\n## Limitations\n\nRead these so you know what the numbers mean.\n\n- **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.\n- **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`.\n- **Top apps covers the last three calendar months only.** That window is fixed by OP3, not configurable.\n- **Data starts when the prefix was added.** OP3 cannot report on downloads that never went through its redirect.\n- **Bots are excluded by default** in OP3's download queries, which is usually what you want.\n- **Rate limits are not publicly documented.** Keep `limit` and `max_records` modest. The server surfaces a clear error on HTTP 429.\n\n### Typed errors\n\nAPI 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`:\n\n- `AuthError` (401/403) — the OP3 token is missing or invalid.\n- `RateLimitError` (429) — too many requests against the OP3 API.\n- `NotFoundError` (404) — the show, feed, or resource doesn't exist (or isn't on OP3 yet).\n- `ValidationError` (400) — a malformed or invalid request parameter.\n- `ServerError` (5xx) — a failure on OP3's side; the specific status (500, 502, 503, ...) is preserved in the message.\n- `OP3APIError` — the base class, used as a fallback for unmapped status codes or network failures.\n\nEvery 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.\n\n## Development\n\n```bash\ngit clone https://github.com/conorbronsdon/op3-mcp.git\ncd op3-mcp\nnpm install\nnpm run build\nnpm test\n```\n\nRun locally:\n\n```bash\nOP3_API_TOKEN=your-token npm start\n```\n\nTests mock `fetch` and make no network calls.\n\n## Contributing\n\nIssues 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.\n\n## About\n\nBuilt 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.\n\nCompanion tools:\n\n- [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.\n- [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.\n- [substack-mcp](https://github.com/conorbronsdon/substack-mcp): read posts and manage drafts on Substack, safe for agent workflows.\n- [podcastindex-mcp](https://github.com/conorbronsdon/podcastindex-mcp): the Podcast Index MCP server, search by person or topic, trending shows, feed health.\n- [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.\n\nMore 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).\n\n---\n\n## Disclaimer\n\n*This is an independent personal project, not affiliated with, sponsored by, or endorsed by any company. All views expressed are my own.*\n\n## License\n\nMIT\n", "bytes": 9926, "sha": "b5d7d75beda2ab0ed5e37a88159c8dffa6b91e450cc33b2421c6c521212bc643", "repo_slug": "conorbronsdon/op3-mcp", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_conorbronsdon_op3_mcp_567cfba6/readme" }