Dub MCP Server & CLI

A free, open source Dub MCP server and CLI that lets Claude Code, Codex, Cursor and other AI agents create short links, read clicks and sales, and run your partner program.

Navid Moazzezby Navid Moazzez·Updated Oct 5, 2026·15 min read·
Your computer
  1. 1

    Add it with a single command in a terminal.

    Put your own API key in place of the example.

    claude mcp add dub \
    -e DUB_API_KEY=YOUR_API_KEY \
    -- npx -y @thenavidm/dub-mcp-cli@latest
  2. 2

    In Claude Code, type /mcp. Dub should show as connected.

    /mcp

Needs Node 22 or newer and a Dub API key. Make one in a minute.

It's free and open source. If it saves you time, star it on GitHub, so more people find it.

Rate this tool

This free Dub MCP server and CLI gives your AI real access to your Dub workspace: short links, analytics, domains, customers and your partner program. It creates and edits short links, reads clicks, leads and sales, sorts links into tags and folders, manages domains, and runs your partner program's applications, commissions and payouts.

It's one install with two ways in. Claude, Codex, Cursor or any other MCP app calls its 61 tools for you, and the same tools work as a CLI that agents like Claude Code, Codex and OpenCode run, or that you type yourself.

In this guide, I'll show you:

  • What the Dub MCP server & CLI is, and what you can ask it
  • How to install it and check that it works
  • When to use the MCP server, and when the CLI
  • Every tool, and how to keep your account safe

Every tool on this page comes from the server itself, and every cost was measured in Claude Code.

key_takeaways.mdTL;DR

Key takeaways

It gives Claude, Codex, Cursor and any other MCP app 61 tools for Dub: short links, analytics, tags, folders, domains, conversions and your partner program.
It uses a Dub API key that you can limit to read-only, or to only the parts of your workspace you pick.
Every new link, change, delete and partner decision waits for your approval.
The same tools run as a CLI, which costs your AI nothing until it runs.

What is the Dub MCP server & CLI?

The Dub MCP server & CLI is a free, open source program that lets AI agents manage your Dub short links and partner program for you, in two ways. The MCP server is what an AI app like Claude, Codex or Cursor connects to, through MCP (Model Context Protocol), the open standard AI apps use to call outside tools.

You ask in plain language. Your AI picks the right tool, and the server makes the call to Dub's own API.

The CLI is the same program as commands. dub-cli list-links runs the same code your AI runs when you ask for your short links, whether an agent like Claude Code runs it or you do.

In an AI OS, the layer that connects your AI to your context, your data and your tools, a server like this is how your AI reaches Dub. I explain how the parts fit together in how to build an AI operating system, and here's how I use AI myself.

What can you ask it?

Once it's set up, you ask the way you'd ask an assistant. These are real prompts it handles:

Try asking
Make a short link to my new course page, with UTM tags for my newsletter.
Which of my links got the most clicks last week?
Move all my webinar links into a Webinars folder.
Show me the partner applications waiting for review.
How many sales did each partner bring in this month?
Make a QR code for my course link.

The first one shows why this is useful. Your AI builds the link with the right UTM tags in one step, and you approve it before it's created.

It works well next to my Kit MCP server and WordPress MCP server, so your AI can draft emails with your links and put them in your posts in the same chat. Every server I've made is on my MCP servers page.

For your links, my free UTM builder and QR code generator help too.

How to install the Dub MCP server

Pick your app in the box at the top of this page. Each one is a single command or a pasted block, and they all run through npx, so there's nothing to install first.

Windsurf, Zed and Cline take the same server, though they don't have a tab in the box yet. Follow the box's Cursor tab, and put its block here instead:

AppWhere the block goes
WindsurfIn the Cascade panel, open the Actions menu (…) and choose Open MCP config file, then paste the block.
ClineClick the MCP Servers icon in the Cline panel, open the Configure tab, click Configure MCP Servers, and paste the block.
ZedGo to Settings, then AI, then MCP Servers, and choose Add Server, then Add Local Server. Enter the block's command, arguments and variables, and Zed saves them under context_servers.
Before you start0/3

Watch out: Dub shows a new API key only once. Copy it right after you click Create API Key.

Set up your Dub account

It takes a minute.

Create an API key0/5

A key belongs to one workspace, so make one in each workspace you want to connect.

Dub limits each key's requests by plan, and analytics have a limit of their own:

Free
Requests a minute
60
Analytics
Not available
Pro
Requests a minute
600
Analytics
2 a second
Business
Requests a minute
1,200
Analytics
4 a second
Advanced
Requests a minute
3,000
Analytics
8 a second

To keep the key out of your app's config, save it alone in a file only you can read, and point DUB_TOKEN_FILE at that file's full path instead.

Check that it works

Run the doctor with --network. It checks your settings, then reads one link to prove the key works. It prints only the count, and it never changes anything.

npx -y @thenavidm/dub-mcp-cli doctor --network

When every line has a check mark, restart your app and ask it for your newest links. A failed check usually means the key is from a different workspace, or it can't read links.

In Claude Code, /mcp also shows whether the Dub server is connected. It's one of the Claude Code commands worth knowing.

Use the Dub CLI

The CLI is the same 61 tools as commands. AI 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 or a script.

Every tool name becomes a command with dashes, so list_links runs as dub-cli list-links.

npm install -g @thenavidm/dub-mcp-cli
dub-cli
dub-cli list-links --page-size 10
dub-cli create-link --url https://example.com/course --key course --utm-source newsletter --confirm
dub-cli get-link-stats --event clicks --interval 7d
dub-cli get-qr-code --url https://dub.sh/course --output-file ~/qr/course.png --confirm

The bare dub-cli lists every command, dub-cli which <words> finds the command for a task, and dub-cli <command> --help shows what a command takes. Every new link, change, delete, conversion, partner decision and saved file needs --confirm, the terminal's version of your approval.

dub-cli install <app> adds the server to Claude Code, Codex, Claude Desktop, Cursor, VS Code or Gemini CLI, in each app's own format.

These are the flags you'll use most:

FlagWhat it does
--jsonPrints JSON
--compactPrints the JSON on one line
--select a,b.cKeeps only those fields, and a dotted path goes deeper
--agentMachine mode: compact JSON, no prompts, and it never confirms anything
--confirmLets a write that asks first go ahead
--dry-runShows what a write would do, without doing it

A script can branch on the exit code:

Exit codeWhat it means
0It worked
1Something unexpected went wrong
2The command was typed wrong, or a write needed --confirm
3It wasn't found
4Dub rejected the credentials
5Dub failed or couldn't be reached
7You hit a rate limit, so wait and try again
10Nothing is set up yet

MCP server or CLI: which one?

Both are the same program with the same 61 tools. The difference is when your AI pays for them, in the tokens it reads.

Every message, in an app that loads every tool
MCP server
74,200 tokens
CLI
Nothing
Every message, in Claude Code
MCP server
1,100 tokens
CLI
Nothing
When Dub comes up
MCP server
Nothing more, or in Claude Code the tools it picks
CLI
4,400 tokens, once
20 messages with Dub in one, every tool loaded
MCP server
1,485,000 tokens
CLI
4,400 tokens
Works in Claude Desktop's chat
MCP server
Yes
CLI
No, there's no terminal there
Works in a script, a cron job or CI
MCP server
No
CLI
Yes

An app that loads every tool up front sends the full list with every message, whether you mention Dub or not. Claude Code doesn't by default: its tool search sends only the tool names and the server's instructions, and loads a tool's full definition when your AI reaches for it.

The CLI costs nothing until Dub comes up. Then your agent reads its skill file once and runs the commands it needs. With the skill added, Claude Code also lists its one-line description with every message, about 60 tokens.

When the whole conversation is about Dub, the gap closes. Then the MCP server is the better experience, because you ask in plain language and your AI never has to look up a command.

How to spend less

In Claude Code, leave tool search on, which it is unless you've set ENABLE_TOOL_SEARCH=false.

Turn the server off when you aren't working on links. In Claude Code that's the /mcp panel, and every AI app has its own switch. DUB_READ_ONLY=1 cuts it to the 22 reading tools.

Or install the CLI and connect the server later, on the days it earns its place. Every tool stays in reach, and the standing cost drops to nothing.

Every number here was measured on October 5, 2026 in Claude Code 2.1.286 with Claude Opus 5.5. It's the same one-line prompt with and without the server connected, once with tool search off so every tool loads, and once with Claude Code's default. The skill was measured the same way, and other apps and models count tokens a little differently.

bulk_create_links, bulk_update_links and bulk_delete_links handle up to 100 links at a time. Dub can accept a bulk request and still refuse some links in it, so your AI reads each result instead of assuming they all went through.

Deleting a domain is permanent, and it deletes every link on that domain too. Deleting a tag or a folder keeps the links working.

Your partner program has its own tools. Approving or rejecting an application notifies the partner, banning one disables their links and cancels their commissions, and deactivating one disables their links but keeps their commissions and payouts. A new commission can come back as a task Dub is still working on, not a finished payment.

get_qr_code saves a link's QR code as a PNG in a new private file, and create_referrals_embed_token saves its token the same way, because that token gives access to a referral dashboard.

For several link, tag or folder changes at once, preview_link_batch checks up to 20 of them on your computer and gives the batch a fingerprint, and submit_link_batch runs them in order only with that same fingerprint.

Watch out: Tracking a lead or a sale counts toward your analytics and your partners' commissions, so the server asks first for those too.

Every Dub tool

The tables below list all 61 tools, grouped by what they're for. Of these, 22 only read, and 39 change something in your Dub workspace or on your computer.

create_link
What it does
Creates a short link, with tags, a folder, UTM tags, an expiry date or A/B tests.
Kind
Asks first
list_links
What it does
Lists your short links, with search and filters.
Kind
Reads
get_links_count
What it does
Counts your short links, with the same filters.
Kind
Reads
get_link
What it does
Reads one short link, by ID, external ID, or domain and key.
Kind
Reads
update_link
What it does
Changes a short link.
Kind
Asks first
delete_link
What it does
Deletes a short link.
Kind
Asks first
bulk_create_links
What it does
Creates up to 100 short links at once.
Kind
Asks first
bulk_update_links
What it does
Makes the same change to up to 100 short links.
Kind
Asks first
bulk_delete_links
What it does
Deletes up to 100 short links.
Kind
Asks first
upsert_link
What it does
Creates a short link for a URL, or returns and updates the one that already exists.
Kind
Asks first
get_qr_code
What it does
Saves a link's QR code as a PNG in a new private file.
Kind
Asks first

Analytics

get_link_stats
What it does
Reads clicks, leads and sales for a link, a domain or your whole workspace.
Kind
Reads
list_events
What it does
Lists click, lead and sale events.
Kind
Reads

Tags and folders

create_tag
What it does
Creates a tag.
Kind
Asks first
list_tags
What it does
Lists your tags.
Kind
Reads
update_tag
What it does
Changes a tag.
Kind
Asks first
delete_tag
What it does
Deletes a tag, and keeps its links working.
Kind
Asks first
create_folder
What it does
Creates a folder.
Kind
Asks first
list_folders
What it does
Lists your folders.
Kind
Reads
update_folder
What it does
Changes a folder.
Kind
Asks first
delete_folder
What it does
Deletes a folder, and keeps its links working.
Kind
Asks first

Domains

create_domain
What it does
Adds a custom domain.
Kind
Asks first
list_domains
What it does
Lists your domains.
Kind
Reads
update_domain
What it does
Changes a domain's settings.
Kind
Asks first
delete_domain
What it does
Deletes a domain and every link on it, for good.
Kind
Asks first
register_domain
What it does
Buys a domain through Dub, on the Enterprise plan only.
Kind
Asks first
check_domain_status
What it does
Checks whether domain names are free to buy.
Kind
Reads

Conversions and customers

track_lead
What it does
Records a lead for a short link, like a signup.
Kind
Asks first
track_sale
What it does
Records a sale for a short link.
Kind
Asks first
track_open
What it does
Records an app open from a Dub deep link.
Kind
Asks first
list_customers
What it does
Lists your customers.
Kind
Reads
get_customer
What it does
Reads one customer, by ID or external ID.
Kind
Reads
update_customer
What it does
Changes a customer.
Kind
Asks first
delete_customer
What it does
Deletes a customer.
Kind
Asks first

Partners and applications

create_partner
What it does
Adds a partner to your program, or updates the one with the same email.
Kind
Asks first
list_partners
What it does
Lists your program's partners.
Kind
Reads
create_partner_link
What it does
Creates a link for a partner in your program.
Kind
Asks first
retrieve_partner_links
What it does
Lists a partner's links.
Kind
Reads
upsert_partner_link
What it does
Creates a partner link for a URL, or returns the one that already exists.
Kind
Asks first
retrieve_partner_analytics
What it does
Reads a partner's clicks, leads and sales.
Kind
Reads
ban_partner
What it does
Bans a partner, which disables their links and cancels their commissions.
Kind
Asks first
deactivate_partner
What it does
Deactivates a partner and disables their links, and keeps their commissions and payouts.
Kind
Asks first
list_program_applications
What it does
Lists partner applications: pending, approved or rejected.
Kind
Reads
approve_program_application
What it does
Approves a partner application, and the partner is told.
Kind
Asks first
reject_program_application
What it does
Rejects a partner application, and the partner gets an email.
Kind
Asks first
create_referrals_embed_token
What it does
Makes a token for your referral dashboard embed, saved to a new private file.
Kind
Asks first

Discounts, commissions, payouts and bounties

list_discount_codes
What it does
Lists your program's discount codes.
Kind
Reads
create_discount_code
What it does
Creates a discount code for a partner.
Kind
Asks first
delete_discount_code
What it does
Deletes a discount code, and turns it off in your connected payment provider too.
Kind
Asks first
create_commission
What it does
Adds a commission for a partner, or a clawback with a negative amount.
Kind
Asks first
list_commissions
What it does
Lists your program's commissions.
Kind
Reads
update_commission
What it does
Changes a commission's amount, like after a refund.
Kind
Asks first
bulk_update_commissions
What it does
Sets the same status on up to 100 commissions.
Kind
Asks first
list_payouts
What it does
Lists your program's payouts.
Kind
Reads
list_bounty_submissions
What it does
Lists the submissions for one bounty.
Kind
Reads
approve_bounty_submission
What it does
Approves a bounty submission, with a custom reward if you like.
Kind
Asks first
reject_bounty_submission
What it does
Rejects a bounty submission, with a reason.
Kind
Asks first

Your workspaces and batches

list_accounts
What it does
Lists the workspaces you've set up, without their keys.
Kind
Reads
get_operation_schema
What it does
Shows every field one of these requests takes.
Kind
Reads
preview_link_batch
What it does
Checks up to 20 link, tag or folder changes on your computer and gives the batch a fingerprint.
Kind
Reads
submit_link_batch
What it does
Runs a checked batch in order, only with the fingerprint from its preview.
Kind
Asks first

Is the Dub MCP server safe?

A link change reaches everyone who clicks it, and partner decisions touch real people's money. So 39 tools ask first: every new link, change and delete, every conversion you track, every partner and commission decision, and every file the server saves. They're the ones marked "Asks first" in the tool tables above.

Reading your links, analytics and partners never asks, because it changes nothing.

When your AI calls one of them, the call needs a yes first. Where you use it decides who gives it:

  • Claude Code (2.1.246 and later) asks you before every call, in every one of its permission modes.
  • An app that can show forms asks you in a form.
  • Any other app takes your AI's confirm: true as the yes, so tell your AI to check with you first.
  • An agent with no person to ask needs DUB_CONFIRM=model, so its confirm: true counts in every app.
  • In a terminal, you add --confirm to the command.

If the answer is no, nothing reaches Dub.

Make it read-only

Set DUB_READ_ONLY=1 and every tool that asks first disappears from the tool list, leaving 22 reading tools. A read-only key does the same at Dub's end.

Keep a log of every write

Set DUB_AUDIT_LOG to a file path. The server writes one line per attempted write, allowed or blocked, with what it was about to do and who approved it.

Watch out: Link titles, partner applications and customer details can be written by other people, and one can try to give your AI orders. Treat them as data, and use DUB_READ_ONLY=1 for an agent working on its own.

Your data

Your requests go straight to Dub, with no server of ours in between and no tracking. Your key stays in your app's config, your shell or your token file.

Customers, partners and commissions are personal and financial data, so keep anything you save private.

To cut access, delete the key under Settings, then API Keys, and remove the server from your app's config.

Connect more than one Dub workspace

Each key belongs to one workspace, so each workspace is its own account here. Set DUB_ACCOUNTS to a JSON list with a name and a key, or a token file, for each workspace, and DUB_DEFAULT_ACCOUNT to the one that acts when a tool names none. Every tool takes an optional account.

A workspace never borrows another one's key. If the workspace you name has no key, the call stops instead of changing a different workspace.

Dub MCP server settings

Every setting is an environment variable, in your app's config or your shell.

DUB_API_KEY
Default
none
What it does
Holds your workspace's API key
DUB_TOKEN_FILE
Default
none
What it does
Points at a private file holding the key, instead
DUB_ACCOUNTS
Default
none
What it does
Lists several workspaces, as JSON
DUB_DEFAULT_ACCOUNT
Default
the first one
What it does
Picks the workspace that acts when a tool names none
DUB_REQUEST_TIMEOUT_MS
Default
30000
What it does
Gives up on a Dub request after this many milliseconds
DUB_MIN_REQUEST_INTERVAL_MS
Default
1100
What it does
Waits this many milliseconds between requests, which suits the Free plan's limit
DUB_READ_ONLY
Default
off
What it does
1 hides every tool that changes something
DUB_ALLOW_DESTRUCTIVE
Default
on
What it does
0 refuses the tools that ask first
DUB_AUDIT_LOG
Default
none
What it does
Names a file that gets one line per attempted write
DUB_SURFACE
Default
full
What it does
search lists three tools that find, describe and run the rest
DUB_TOOL_TIMEOUT_MS
Default
none
What it does
Gives up on any tool after this many milliseconds
DUB_CONFIRM
Default
human
What it does
model lets your AI's confirm: true approve on its own, for an agent with no person to ask
DUB_HTTP_PORT
Default
8787
What it does
Sets the port for --http
DUB_HTTP_HOST
Default
127.0.0.1
What it does
Sets the address for --http, and any other needs a token
DUB_HTTP_TOKEN
Default
none
What it does
Sets the bearer token every --http request needs
DUB_HTTP_ALLOWED_ORIGINS
Default
none
What it does
Lists other websites allowed to call --http, comma separated
DUB_DEBUG
Default
off
What it does
1 prints debug lines

Troubleshooting

Run the doctor first. It names the step that failed and the fix.

What you seeWhat to do
The key check failsThe key is from a different workspace, or it can't read links. Check its permissions under Settings, then API Keys
Analytics are refusedAnalytics through the API need a paid plan
A bulk request worked, but some links are missingDub refused those links. Read each result, and don't send the ones that worked again
A 429 errorYou're over your plan's requests a minute, or the analytics limit. Wait, then try again
A new commission isn't there yetDub accepted it as a task that's still running. Check again in a moment
A saved file is refusedThe server never overwrites a file. Pick a new file name
"…so it will not run without confirm: true"That's the safety check working. Approve it when your app asks

If the server doesn't show up in your app at all, run the command your app runs, in a terminal, and read the error.

More free tools for your links

Send your links to your email list, or sell what they point to.

FAQs about the Dub MCP server & CLI

Here are the questions people ask most about the Dub MCP server and CLI.

The Dub MCP server & CLI is a free, open source program that lets an AI app like Claude, Codex or Cursor manage your Dub short links and partner program.

It has 61 tools for short links, analytics, domains, conversions and partner programs, and the same tools run as a CLI that agents like Claude Code and Codex use, or that you type yourself.

An MCP server is a standard way to give an AI app real access to a tool, so it can act instead of guessing.

MCP stands for Model Context Protocol, and Claude, Codex, Cursor and many other AI apps speak it.

Every server I've made is on my MCP servers page.

The Dub CLI is the same program as the Dub MCP server, run as commands.

AI agents like Claude Code, Codex and OpenCode run them for you, and you can type them in a terminal or a script.

One npm package installs both.

Use the Dub MCP server in an AI app with no terminal, like Claude Desktop's chat, and the CLI in a terminal, a script or a cron job.

In an AI app that can run commands, like Claude Code, Codex or Cursor, the CLI is the lighter choice, because it costs nothing until it runs.

Yes, the Dub MCP server is free and open source under the AGPL-3.0 license.

Dub's API works on every plan, Free included, though analytics through the API need a paid plan.

Yes, Dub's API works on the Free plan, with 60 requests a minute per key.

Analytics through the API need a paid plan, starting with Pro.

Yes, Dub lets you make a key with read-only permissions, or with access to only certain parts of your workspace.

A read-only key can't change anything, even if a tool asks.

Yes, it reads partners, applications, commissions and payouts, and approves or rejects applications after you approve.

It never sends a payout, since the server has no tool for that.

Yes, the Dub MCP server connects as many workspaces as you set up in DUB_ACCOUNTS, each with its own key.

Every tool takes an optional account, and a workspace never borrows another one's key.

To disconnect the Dub MCP server, delete its key under Settings, then API Keys, which cuts access right away.

Then remove the server from your AI app's config.

The Dub MCP server works with any app that speaks MCP.

That includes Claude Code, Claude Desktop, Codex, Cursor, VS Code, Windsurf, Zed, Cline, GitHub Copilot CLI, Gemini CLI, OpenCode, OpenClaw, Antigravity and Hermes.

I did.

I'm Navid Moazzez, and I made the Dub MCP server & CLI as one of my free tools on navid.me.

You can read more about me.

The code is on GitHub under the AGPL-3.0 license, and the package is on npm.

More MCP servers & CLIs

Related free tools

Navid Moazzez

AI business strategist

Navid Moazzez helps creators and founders master AI and build their own AI Operating System (AI OS) to automate their business and life.

Navid.me is reader-supported. When you buy through links on this site, I may earn an affiliate commission. Read the affiliate disclaimer.

Free AI newsletter

The most actionable AI newsletter for founders

Every week, get proven AI strategies, curated tools, and step-by-step systems to grow your audience, create better content, and build a profitable creator business.

No fluff, no filler, no BS. Just five minutes each week that might level up your online business and life.

P.S. Sign up now to get free access to my ultimate AI tools guide for creators.

Loved by 10,000+ readers
Loved by 10,000+ readers