OP3 MCP Server & CLI

OP3 MCP

OP3 sits in front of the audio file, so it counts every download whatever app made it.

That is why its numbers differ from Apple's or Spotify's, which each report only their own listeners.

22 tools, including unique listeners, retention cohorts and episode benchmark curves that OP3's own API does not expose.

Built and maintained by Navid Moazzez. Built on Slipway, which turns one definition of each tool into the MCP server and the CLI.

Two ways to use it

Command line

op3-cli runs every tool as a command. Agents that run commands, like Claude Code, Codex and OpenCode, use it on their own, and you can type the same commands in a terminal, a script or a cron job:

npm install -g @thenavidm/op3-mcp-cli
op3-cli                                   # every command
op3-cli op3-global-app-share --agent
op3-cli op3-get-show --identifier https://feeds.example.com/show.xml
op3-cli op3-show-downloads --help
op3-cli which listener retention          # find the command for a task

Every command reads OP3's public data, so nothing asks for --confirm. --agent is JSON on one line for scripts and agents, and --select a,b.c keeps only the fields you name.

op3-cli schema <command> prints the exact JSON Schema an MCP client receives for that tool.

MCP server, for AI agents

op3-mcp is what Claude Code, Claude Desktop, Cursor and the rest launch. You never run it by hand:

claude mcp add op3 -- npx -y @thenavidm/op3-mcp-cli

In Claude Desktop, the .mcpb extension installs on a double click. Section 4 has every other client.

Contents

1. What you can ask it
2. Quick install
3. Setup
4. Connect your client
5. Check it worked
6. What it costs to have connected
7. Tools
8. Reading the numbers
9. Your data
10. Troubleshooting

1. What you can ask it 💬

• How many downloads did my podcast get this month?
• How many actual people is that, not downloads?
• Are my listeners coming back, or is it a new audience every month?
• Is this week's episode tracking ahead or behind my usual?
• Where in the world is my audience, down to the state?
• Which podcast apps do my listeners use, and is that unusual?
• Compare my show against these three others.
• What day and hour do most downloads happen?
• Which of my episodes share the same listeners?
• OP3 shows nothing for my feed. What is wrong?

The one that is impossible without this server is the second. Every podcast analytics dashboard reports downloads. A download is an app fetching a file, not a person, and one listener whose app re-requests across three days counts three times. OP3's raw rows carry a privacy-preserving per-listener hash, so unique listeners, returning listeners and retention can be computed from them. None of OP3's own aggregated endpoints expose that, and this server does.

2. Quick install ⚡

Node 22 or newer. Nothing else.

npx -y @thenavidm/op3-mcp-cli@latest --version

That is the whole install. npx fetches it on demand, so there is nothing to update later: with @latest, a new version reaches you the next time your client starts the server.

To build from source instead:

git clone https://github.com/thenavidm/op3-mcp-cli.git
cd op3-mcp
npm install
npm run build
npm test
node dist/index.js --version

3. Setup 🔑

You can skip this. The server works with no credential at all, because OP3 publishes a shared preview token and that is what it falls back to. It is rate limited and OP3 can withdraw it, so get your own before relying on it.

Have an agent do it

The agent cannot sign in to OP3 for you. What it can do is walk you through it and wire up the config.

Paste this into Claude Code, Cursor, or any agent with terminal access:

Help me set up the OP3 MCP server.

1. Open https://op3.dev/api/keys and tell me what to click to create an
   API key and its bearer token.
2. Stop and wait for me to paste the token back.
3. Add the server to my MCP client config with that token as OP3_TOKEN.
4. Run the doctor command and tell me whether it worked.

Or do it yourself

1. Go to op3.dev/api/keys.
2. Create an API key and copy its bearer token.
3. Set it as OP3_TOKEN in your client config, as in section 4.

You do not need to own a podcast. The token reads public OP3 data, which covers every show that has the OP3 prefix on its feed.

To revoke

Delete the key at op3.dev/api/keys. It stops working immediately.

If you want your own show in here

Your podcast needs the OP3 prefix on its episode audio URLs. That is a change to your feed, not to this server, and it is documented at op3.dev/setup. Until a listener downloads an episode through the prefix, OP3 has no data for your show and neither does this.

4. Connect your client 🔌

The long version, every step with what to do when one fails, is in INSTALL.md.

OP3_TOKEN is optional in every block below. Leave it out to use OP3's preview token.

Claude Code

claude mcp add op3 \
  -e OP3_TOKEN=your-token \
  -- npx -y @thenavidm/op3-mcp-cli@latest

Add --scope user to make it available in every project rather than just this one.

Claude Desktop

The short way: download the .mcpb extension from the latest release and double-click it. It carries its own dependencies, so there is no config file to edit and nothing to install first. It asks for an OP3 token, which is optional.

The long way, if you would rather edit the config yourself:

{
  "mcpServers": {
    "op3": {
      "command": "npx",
      "args": ["-y", "@thenavidm/op3-mcp-cli@latest"],
      "env": { "OP3_TOKEN": "your-token" }
    }
  }
}

Tip Claude Desktop does not inherit your shell PATH. If npx is not found, use the absolute path from which npx.

Quit Claude Desktop completely and reopen it.

claude.ai on the web

claude.ai runs a connector from Anthropic's cloud rather than your machine, so it cannot launch a local command. It needs a public HTTPS URL.

Run the server over HTTP:

npx -y @thenavidm/op3-mcp-cli@latest --http --port 8000

Host it somewhere with a public HTTPS URL, then in claude.ai go to Customize, Connectors, +, Add custom connector, paste the URL and click Add.

On Team and Enterprise plans an owner adds it first under Organization settings, Connectors, then each member enables it under Customize, Connectors.

It binds to 127.0.0.1 by default, which is all a tunnel or a proxy on the same machine needs. To accept connections from outside the machine, set OP3_HTTP_HOST=0.0.0.0 together with OP3_HTTP_TOKEN, a bearer token every request must send: without one, the server refuses to listen beyond this machine.

Cursor

.cursor/mcp.json, same JSON shape as Claude Desktop, key mcpServers.

Windsurf

~/.codeium/windsurf/mcp_config.json, key mcpServers.

VS Code

.vscode/mcp.json. The key is servers, not mcpServers, and each entry takes "type": "stdio".

{
  "servers": {
    "op3": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@thenavidm/op3-mcp-cli@latest"],
      "env": { "OP3_TOKEN": "your-token" }
    }
  }
}

Codex CLI

~/.codex/config.toml:

[mcp_servers.op3]
command = "npx"
args = ["-y", "@thenavidm/op3-mcp-cli@latest"]

[mcp_servers.op3.env]
OP3_TOKEN = "your-token"

Gemini CLI

~/.gemini/settings.json, key mcpServers.

Everything else

Any stdio MCP client takes the same three things: the command npx, the args, and the env block.

Docker

docker build -t op3-mcp .
docker run --rm -i -e OP3_TOKEN=your-token op3-mcp

5. Check it worked 🩺

npx -y @thenavidm/op3-mcp-cli@latest doctor

It tests the token against the cheapest OP3 endpoint, tests the raw query endpoints separately because they fail for their own reasons, and prints the settings in force.