Gumroad MCP Server & CLI

A free, open source Gumroad MCP server and CLI that lets Claude Code, Codex, Cursor and other AI agents read your sales and payouts, refund orders and manage products and license keys.

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

    Add it with a single command in a terminal.

    Put your own access token in place of the example.

    claude mcp add gumroad \
    -e GUMROAD_ACCESS_TOKEN=YOUR_ACCESS_TOKEN \
    -- npx -y @thenavidm/gumroad-mcp-cli@latest
  2. 2

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

    /mcp

Needs Node 22 or newer and a Gumroad access token. Get 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 Gumroad MCP server and CLI gives your AI real access to your Gumroad store: products, sales, subscribers, license keys, discounts and payouts. It reads your products, sales and payouts, refunds and ships orders, manages variants, discount codes and checkout fields, and checks license keys.

It's one install with two ways in. Claude, Codex, Cursor or any other MCP app calls its 57 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 Gumroad 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 57 tools for Gumroad: products, sales, refunds, subscribers, license keys, discounts, payouts and webhooks.
It uses an access token you generate under Settings, then Advanced, in about a minute.
Every refund, product change, license change and receipt email waits for your approval.
The same tools run as a CLI, which costs your AI nothing until it runs.

What is the Gumroad MCP server & CLI?

The Gumroad MCP server & CLI is a free, open source program that lets AI agents run your Gumroad store 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 Gumroad's own API.

The CLI is the same program as commands. gumroad-cli list-sales runs the same code your AI runs when you ask how your sales went, 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 Gumroad. 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
How many sales did I make last month, and which product sold best?
Refund the order from jane@example.com in full.
Make a 20% off code called SPRING for my course.
Is this customer's license key still valid for my plugin?
When is my next payout, and how much will it be?
Turn off my old ebook so nobody can buy it.

The fourth one shows why this is useful. Your AI checks the key without using up one of its activations, so a support question never costs your customer a use.

It works well next to my Kit MCP server and Dub MCP server, so your AI can email your buyers and see which links lead to sales in the same chat. Every server I've made is on my MCP servers page.

For your pricing, my free Gumroad fee calculator and digital product idea generator help too. Gumroad is one of the platforms I compare in the best place to sell digital products.

How to install the Gumroad 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

Pro tip: Gumroad's application form asks for a redirect URI. It doesn't matter for a token you use yourself, so http://127.0.0.1 is fine.

Set up your Gumroad account

It takes a minute.

Get your access token0/5

You can find the token again later on the same page, under your application.

To check a customer's license key, put the key into GUMROAD_LICENSE_KEY instead of the chat, so the key itself never shows up in what your AI reads. Checking a key needs no access token.

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

Check that it works

Run the doctor with --network. It checks your settings, then reads your seller profile to prove the token works. It doesn't change anything.

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

When every line has a check mark, restart your app and ask it for your products. A failed check usually means the token was mistyped, or the application was deleted.

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

Use the Gumroad CLI

The CLI is the same 57 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_sales runs as gumroad-cli list-sales.

npm install -g @thenavidm/gumroad-mcp-cli
gumroad-cli
gumroad-cli list-products
gumroad-cli list-sales --after 2026-09-01 --before 2026-09-30
gumroad-cli get-upcoming-payout
gumroad-cli refund-sale --sale-id YOUR_SALE_ID --full-refund --confirm

The bare gumroad-cli lists every command, gumroad-cli which <words> finds the command for a task, and gumroad-cli <command> --help shows what a command takes. Refunds, product changes, license changes, receipt emails and exports need --confirm, the terminal's version of your approval.

gumroad-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
4Gumroad rejected the credentials
5Gumroad 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 57 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
22,100 tokens
CLI
Nothing
Every message, in Claude Code
MCP server
1,100 tokens
CLI
Nothing
When Gumroad comes up
MCP server
Nothing more, or in Claude Code the tools it picks
CLI
4,500 tokens, once
20 messages with Gumroad in one, every tool loaded
MCP server
443,000 tokens
CLI
4,500 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 Gumroad 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 Gumroad 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 Gumroad, 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 your store. In Claude Code that's the /mcp panel, and every AI app has its own switch. GUMROAD_READ_ONLY=1 cuts it to the 25 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.

Refunds, licenses and checkout

refund_sale refunds in full, or in part with an amount in the sale's own currency, in its smallest unit. 200 means 2.00 in most currencies but ¥200 in Japanese yen, so your AI reads the sale before it suggests an amount.

Refunding, taking away a buyer's access, resending a receipt and marking a sale shipped are separate actions, and each one asks first. A resent receipt is a real email to your buyer.

verify_license checks a license key without using up one of its uses, and increment_license_uses is the separate tool that counts one. rotate_license replaces a key for good, and saves the new key to a private file instead of showing it in chat.

Variants, discount codes and checkout fields live on each product. A discount is cents off or a percentage from 1 to 100. Gumroad calls its webhooks resource subscriptions, and they cover sales, refunds, disputes and subscription changes.

export_resources saves products, sales, subscribers or payouts to a new private file, 1,000 items unless you ask for more and 10,000 at most. If it stops at its limit, it tells you where to pick up.

Watch out: Disabling a product stops new sales right away, and deleting one can't be undone. Disable it first if you only want it out of sight.

Every Gumroad tool

The tables below list all 57 tools, grouped by what they're for. Of these, 25 only read, and 32 change something in your Gumroad store or on your computer.

Products

list_categories
What it does
Lists Gumroad's product categories.
Kind
Reads
list_products
What it does
Lists your products.
Kind
Reads
get_product
What it does
Reads one product.
Kind
Reads
create_product
What it does
Creates a product, as a draft or published.
Kind
Asks first
update_product
What it does
Changes a product's details.
Kind
Asks first
delete_product
What it does
Deletes a product.
Kind
Asks first
enable_product
What it does
Publishes a product again, so people can buy it.
Kind
Asks first
disable_product
What it does
Unpublishes a product, so nobody can buy it.
Kind
Asks first

Sales and subscribers

list_sales
What it does
Lists your sales, filtered by date, email, order or product.
Kind
Reads
get_sale
What it does
Reads one sale.
Kind
Reads
mark_sale_as_shipped
What it does
Marks a sale as shipped, with a tracking link.
Kind
Asks first
refund_sale
What it does
Refunds a sale, in full or in part.
Kind
Asks first
revoke_sale_access
What it does
Takes away a buyer's access to what they bought.
Kind
Asks first
restore_sale_access
What it does
Gives a buyer their access back.
Kind
Asks first
resend_sale_receipt
What it does
Emails a buyer their receipt again.
Kind
Asks first
list_subscribers
What it does
Lists a membership's subscribers, 100 at a time.
Kind
Reads
get_subscriber
What it does
Reads one subscriber.
Kind
Reads

License keys

verify_license
What it does
Checks a license key without using up one of its uses.
Kind
Reads
enable_license
What it does
Turns a license key back on.
Kind
Asks first
disable_license
What it does
Turns a license key off.
Kind
Asks first
decrement_license_uses
What it does
Takes one use off a license key's count.
Kind
Asks first
rotate_license
What it does
Replaces a license key with a new one, saved to a private file.
Kind
Asks first
increment_license_uses
What it does
Checks a license key and counts one use.
Kind
Asks first

Variants

create_variant_category
What it does
Adds a variant category to a product.
Kind
Asks first
get_variant_category
What it does
Reads one variant category.
Kind
Reads
update_variant_category
What it does
Renames a variant category.
Kind
Asks first
delete_variant_category
What it does
Deletes a variant category.
Kind
Asks first
list_variant_categories
What it does
Lists a product's variant categories, like Size.
Kind
Reads
create_variant
What it does
Adds a variant, with its price difference and purchase limit.
Kind
Asks first
get_variant
What it does
Reads one variant.
Kind
Reads
update_variant
What it does
Changes a variant.
Kind
Asks first
delete_variant
What it does
Deletes a variant.
Kind
Asks first
list_variants
What it does
Lists the options in a variant category, like Small and Large.
Kind
Reads

Discount codes and checkout fields

list_offer_codes
What it does
Lists a product's discount codes.
Kind
Reads
get_offer_code
What it does
Reads one discount code.
Kind
Reads
create_offer_code
What it does
Adds a discount code, in cents or percent off.
Kind
Asks first
update_offer_code
What it does
Changes a discount code's limits.
Kind
Asks first
delete_offer_code
What it does
Deletes a discount code.
Kind
Asks first
list_custom_fields
What it does
Lists a product's checkout fields.
Kind
Reads
create_custom_field
What it does
Adds a checkout field.
Kind
Asks first
update_custom_field
What it does
Changes a checkout field.
Kind
Asks first
delete_custom_field
What it does
Deletes a checkout field.
Kind
Asks first
get_custom_field
What it does
Reads one checkout field by its name.
Kind
Reads

Webhooks

create_resource_subscription
What it does
Adds a webhook for sales, refunds, disputes or subscription changes.
Kind
Asks first
list_resource_subscriptions
What it does
Lists your webhooks for one kind of event.
Kind
Reads
delete_resource_subscription
What it does
Deletes a webhook.
Kind
Asks first

Payouts and refund policy

get_refund_policy
What it does
Reads your refund policy.
Kind
Reads
update_refund_policy
What it does
Changes your refund period or its fine print.
Kind
Asks first
list_payouts
What it does
Lists your payouts.
Kind
Reads
get_payout
What it does
Reads one payout.
Kind
Reads
get_upcoming_payout
What it does
Shows your next payout.
Kind
Reads

Your account, batches and exports

get_user
What it does
Reads your Gumroad seller profile.
Kind
Reads
list_accounts
What it does
Lists the accounts you've set up, without their tokens.
Kind
Reads
get_operation_schema
What it does
Shows every field one of these requests takes, and the scope it needs.
Kind
Reads
preview_commerce_batch
What it does
Checks up to 20 changes on your computer and gives the batch a fingerprint.
Kind
Reads
submit_commerce_batch
What it does
Runs a checked batch in order, only with the fingerprint from its preview.
Kind
Asks first
export_resources
What it does
Saves products, sales, subscribers or payouts to a new private JSON file.
Kind
Asks first

Is the Gumroad MCP server safe?

Money and customer access are on the line. So 32 tools ask first: every refund, access change, receipt email, product or license change, discount, webhook and export. They're the ones marked "Asks first" in the tool tables above.

Reading your products, sales, payouts and license keys 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 GUMROAD_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 Gumroad.

Make it read-only

Set GUMROAD_READ_ONLY=1 and every tool that asks first disappears from the tool list, leaving 25 reading tools. It doesn't narrow the token itself at Gumroad.

Keep a log of every write

Set GUMROAD_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: Product descriptions and buyer details can be written by other people, and one can try to give your AI orders. Treat them as data, and use GUMROAD_READ_ONLY=1 for an agent working on its own.

Your data

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

Sales, subscribers and payouts are your customers' personal and financial data, so keep any export private and delete it when you're done.

To cut access, revoke the token in your application under Settings, then Advanced, and remove the server from your app's config.

Connect more than one Gumroad account

Set GUMROAD_ACCOUNTS to a JSON list with a name and a token, or a token file, for each account, plus a license key or license file where you need one. GUMROAD_DEFAULT_ACCOUNT picks the one that acts when a tool names none, and every tool takes an optional account.

An account never borrows another one's token. If the account you name has no token, the call stops instead of acting in a different store.

Gumroad MCP server settings

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

GUMROAD_ACCESS_TOKEN
Default
none
What it does
Holds your seller access token
GUMROAD_TOKEN_FILE
Default
none
What it does
Points at a private file holding the token, instead
GUMROAD_LICENSE_KEY
Default
none
What it does
Holds a customer's license key, for the license tools
GUMROAD_LICENSE_FILE
Default
none
What it does
Points at a private file holding the license key, instead
GUMROAD_ACCOUNTS
Default
none
What it does
Lists several accounts, as JSON
GUMROAD_DEFAULT_ACCOUNT
Default
the first one
What it does
Picks the account that acts when a tool names none
GUMROAD_REQUEST_TIMEOUT_MS
Default
30000
What it does
Gives up on a Gumroad request after this many milliseconds
GUMROAD_MIN_REQUEST_INTERVAL_MS
Default
1000
What it does
Waits this many milliseconds between requests
GUMROAD_READ_ONLY
Default
off
What it does
1 hides every tool that changes something
GUMROAD_ALLOW_DESTRUCTIVE
Default
on
What it does
0 refuses the tools that ask first
GUMROAD_AUDIT_LOG
Default
none
What it does
Names a file that gets one line per attempted write
GUMROAD_SURFACE
Default
full
What it does
search lists three tools that find, describe and run the rest
GUMROAD_TOOL_TIMEOUT_MS
Default
none
What it does
Gives up on any tool after this many milliseconds
GUMROAD_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
GUMROAD_HTTP_PORT
Default
8787
What it does
Sets the port for --http
GUMROAD_HTTP_HOST
Default
127.0.0.1
What it does
Sets the address for --http, and any other needs a token
GUMROAD_HTTP_TOKEN
Default
none
What it does
Sets the bearer token every --http request needs
GUMROAD_HTTP_ALLOWED_ORIGINS
Default
none
What it does
Lists other websites allowed to call --http, comma separated
GUMROAD_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 token check failsThe token was mistyped, or the application was deleted. Generate a new one under Settings, then Advanced
A license check failsCheck the product ID and the license key. A refunded, disabled or expired purchase fails too
A license's use count went upverify_license never counts a use. Only increment_license_uses does, and it asks first
A refund is refusedGive a full refund or a positive amount in the sale's smallest currency unit, never both
A webhook won't saveCheck the event name, and that the callback URL uses HTTPS
An export stopped at its limitIt tells you where to pick up. Run it again from there, into a new file
"…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 selling online

Run a store on Lemon Squeezy or checkouts on ThriveCart, with the same kind of tools.

FAQs about the Gumroad MCP server & CLI

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

The Gumroad MCP server & CLI is a free, open source program that lets an AI app like Claude, Codex or Cursor run your Gumroad store.

It has 57 tools for products, sales, subscribers, license keys, discounts, payouts and webhooks, 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 Gumroad CLI is the same program as the Gumroad 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 Gumroad 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 Gumroad MCP server is free and open source under the AGPL-3.0 license.

Gumroad's API comes with every seller account, so the only thing you pay for is your own AI app.

Create an application under Settings, then Advanced, with any name and http://127.0.0.1 as the redirect URI.

Then click Generate access token on the next screen.

No, verify_license checks a key without counting a use.

Counting one is a separate tool, increment_license_uses, and it asks first.

Yes, in full or in part, after you approve that exact refund.

A partial refund is in the sale's own currency, in its smallest unit.

Yes, the Gumroad MCP server connects as many accounts as you set up in GUMROAD_ACCOUNTS, each with its own token.

Every tool takes an optional account, and an account never borrows another one's token.

To disconnect the Gumroad MCP server, revoke its token in your application under Settings, then Advanced.

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

The Gumroad 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 Gumroad 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