MCP tools reference

Bandcamp MCP tools

13 tools for Bandcamp on the Cotlet MCP server. Your agent picks them from tools/list.

MCP server
https://cotlet.dev/mcp/v1
Connects with
Your own Bandcamp artist or label account
Integration page
Bandcamp
Bandcamp Endpoints
Endpoint Access Description
bandcamp_list_releases read Albums and tracks on your account with price, release date and visibility.
bandcamp_list_sales read Sales line items for a date range, with the net amount of each.
bandcamp_export_sales_report read One of the three reports from your Tools page for a date range.
bandcamp_list_merch_orders read Orders from your Merch Orders page with items, buyer and shipping address.
bandcamp_list_merch_items read Merch items with price, SKU, quantity sold and quantity available, per option.
bandcamp_list_track_album_codes read Your code batches with how many are redeemed; with batch_id, the codes of one batch.
bandcamp_mark_order_shipped write Mark a merch order shipped; Bandcamp emails the buyer with the tracking number and note.
bandcamp_refund_merch_order write Refund a physical order from the last 180 days and optionally return the item to stock.
bandcamp_update_merch_quantity write Set how many of a merch item or option are available.
bandcamp_update_release write Change the price, title or release date of an album or track.
bandcamp_create_discount_code write New discount code that fans enter in the Buy Now dialog.
bandcamp_generate_track_album_codes write New batch of one-use codes fans redeem for a download, counted against your code allowance.
bandcamp_send_community_message write Post a message to your Community page; followers get it by email and in the Bandcamp app.

List releases

read

MCP tool bandcamp_list_releases

Lists the releases on your account, the same items the Bulk Edit page shows. Filter by digital or physical and by public, private or draft. Use release_id from each item in the other tools.

Parameters

Parameters: list_releases
NameTypeDescription
format enum digital, physical or all. Default: all.
visibility enum public, private, draft or all. Default: all.

tools/call

JSON-RPC 

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "bandcamp_list_releases",
    "arguments": {}
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "releases": [
      {
        "release_id": "r_1840221",
        "title": "Night Drive",
        "format": "digital",
        "visibility": "public",
        "price": 9,
        "currency": "USD",
        "release_date": "2025-11-14",
        "url": "https://yourname.bandcamp.com/album/night-drive"
      },
      {
        "release_id": "r_1902254",
        "title": "Tour EP",
        "format": "digital",
        "visibility": "draft",
        "price": 5,
        "currency": "USD",
        "release_date": "2026-11-01",
        "url": "https://yourname.bandcamp.com/album/tour-ep"
      }
    ]
  },
  "isError": false
}

List sales

read

MCP tool bandcamp_list_sales

Returns the lines of your raw data sales report, oldest first: each line is the sale of an item, a payout or a sale reversal. Use export_sales_report for the revenue summary or the payout statement.

Parameters

Parameters: list_sales
NameTypeDescription
since date Start of the date range. Default: 30 days ago.
until date End of the date range. Default: today.

tools/call

JSON-RPC 

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "bandcamp_list_sales",
    "arguments": {}
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "sales": [
      {
        "date": "2026-09-03T18:22:11Z",
        "type": "sale",
        "item_type": "album",
        "item_name": "Night Drive",
        "quantity": 1,
        "currency": "USD",
        "net_amount": 8.5
      },
      {
        "date": "2026-09-04T09:10:42Z",
        "type": "sale",
        "item_type": "package",
        "item_name": "Night Drive (12\" vinyl)",
        "quantity": 1,
        "currency": "USD",
        "net_amount": 24.1
      }
    ]
  },
  "isError": false
}

Export sales report

read

MCP tool bandcamp_export_sales_report

Returns the report you pick: revenue_summary (gross and net revenue, shipping and tax for a release or the whole catalog), payout_statement (which sales are in each bulk payout) or raw_data. For revenue_summary you can narrow the report to one release.

Parameters

Parameters: export_sales_report
NameTypeDescription
report required enum revenue_summary, payout_statement or raw_data.
since date Start of the date range. Default: 30 days ago.
until date End of the date range. Default: today.
release_id string revenue_summary only: limit the report to this release.

tools/call

JSON-RPC 

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "bandcamp_export_sales_report",
    "arguments": {
      "report": "revenue_summary",
      "since": "2026-09-01",
      "until": "2026-09-30"
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "report": "revenue_summary",
    "since": "2026-09-01",
    "until": "2026-09-30",
    "currency": "USD",
    "gross_revenue": 1842.5,
    "net_revenue": 1713.1,
    "releases": [
      {
        "release_id": "r_1840221",
        "title": "Night Drive",
        "net_revenue": 1204.3
      },
      {
        "release_id": "r_1902254",
        "title": "Tour EP",
        "net_revenue": 508.8
      }
    ]
  },
  "isError": false
}

List merch orders

read

MCP tool bandcamp_list_merch_orders

Lists physical orders from your Merch Orders page, newest first, with the items bought, the buyer, the shipping address and whether the order shipped. By default only unshipped orders. Search by email, last name or Bandcamp payment ID. Pass order_id to mark_order_shipped or refund_merch_order.

Parameters

Parameters: list_merch_orders
NameTypeDescription
unshipped_only boolean Only orders not marked shipped. Default: true.
search string Buyer email, last name or Bandcamp payment ID.
since date Start of the date range. Default: 30 days ago.
until date End of the date range. Default: today.

tools/call

JSON-RPC 

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "bandcamp_list_merch_orders",
    "arguments": {}
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "orders": [
      {
        "order_id": "4471025938",
        "ordered_at": "2026-10-08T14:03:00Z",
        "shipped": false,
        "buyer": {
          "name": "Maya Brandt",
          "email": "maya@example.com"
        },
        "ship_to": {
          "name": "Maya Brandt",
          "city": "Leeds",
          "country": "United Kingdom",
          "country_code": "GB"
        },
        "items": [
          {
            "title": "Night Drive (12\" vinyl)",
            "option": "Black",
            "quantity": 1
          }
        ]
      }
    ]
  },
  "isError": false
}

List merch items

read

MCP tool bandcamp_list_merch_items

Lists the merch on your account with price, SKU, how many were sold and how many are available. Items with sizes or colors list each option. Quantities are kept per shipping origin. An item with no limit shows quantity_available as null.

Parameters

Parameters: list_merch_items
NameTypeDescription
low_stock_below integer Only items with fewer available than this.

tools/call

JSON-RPC 

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "bandcamp_list_merch_items",
    "arguments": {}
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "items": [
      {
        "item_id": "p_1154611570",
        "title": "Band Tote",
        "sku": "GGRA3-1",
        "price": 12,
        "currency": "USD",
        "quantity_sold": 4,
        "quantity_available": 6,
        "options": []
      },
      {
        "item_id": "p_175167691",
        "title": "Night Drive (12\" vinyl)",
        "sku": "ND-LP",
        "price": 25.5,
        "currency": "USD",
        "quantity_sold": 12,
        "quantity_available": 8,
        "options": [
          {
            "item_id": "o_1842702675",
            "title": "Black",
            "sku": "ND-LP-B",
            "quantity_sold": 9,
            "quantity_available": 3
          },
          {
            "item_id": "o_1842702676",
            "title": "Red",
            "sku": "ND-LP-R",
            "quantity_sold": 3,
            "quantity_available": 5
          }
        ]
      }
    ]
  },
  "isError": false
}

List track/album codes

read

MCP tool bandcamp_list_track_album_codes

Without batch_id, returns each batch with its release, size and redeemed count, as the Track/album codes section of your Tools page does. With batch_id, returns every code of that batch and whether it was redeemed.

Parameters

Parameters: list_track_album_codes
NameTypeDescription
batch_id string Batch ID from a previous call. Returns the codes of this batch.

tools/call

JSON-RPC 

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "bandcamp_list_track_album_codes",
    "arguments": {}
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "batches": [
      {
        "batch_id": "b_0042",
        "batch_name": "tour-2026",
        "release_title": "Tour EP",
        "codes": 100,
        "redeemed": 37
      }
    ]
  },
  "isError": false
}

Mark order shipped

write Confirm

MCP tool bandcamp_mark_order_shipped

Marks one order shipped. Bandcamp then emails the buyer with the tracking number and note you pass. One order per call. By default you confirm each call; you can switch that off for this tool.

Parameters

Parameters: mark_order_shipped
NameTypeDescription
order_id required string Order ID from list_merch_orders.
tracking_number string Tracking number shown to the buyer.
note string Note for the buyer in the shipping email.

tools/call

JSON-RPC 

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "bandcamp_mark_order_shipped",
    "arguments": {
      "order_id": "4471025938",
      "tracking_number": "9400111899223344556677",
      "note": "Thanks for the support! Your LP is on its way."
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "order_id": "4471025938",
    "status": "shipped",
    "tracking_number": "9400111899223344556677",
    "note": "Thanks for the support! Your LP is on its way.",
    "buyer_notified": true,
    "items": [
      {
        "title": "Night Drive (12\" vinyl)",
        "option": "Black",
        "quantity": 1
      }
    ]
  },
  "isError": false
}

Refund merch order

write Confirm

MCP tool bandcamp_refund_merch_order

Refunds a physical order the way the "refund this order" link on the Merch Orders page does, and your revenue share adjusts. It works for orders placed in the last 180 days and not under a dispute; for older orders the call fails and you refund the fan yourself, for example through PayPal. Digital purchases are refunded through Bandcamp Support. By default you confirm each call; you can switch that off for this tool.

Parameters

Parameters: refund_merch_order
NameTypeDescription
order_id required string Order ID from list_merch_orders.
return_to_stock boolean Put the item back into your inventory. Default: false.

tools/call

JSON-RPC 

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "bandcamp_refund_merch_order",
    "arguments": {
      "order_id": "order_8c41d2"
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "order_id": "4471025938",
    "status": "refunded",
    "restocked": true
  },
  "isError": false
}

Update merch quantity

write

MCP tool bandcamp_update_merch_quantity

Sets the available quantity of an item or one of its options at a shipping origin. Bandcamp lowers it by itself when an item sells, so use this when you also sell elsewhere. 0 marks the item Sold Out. It runs without asking first: it reaches no one and one more call sets the old number back.

Parameters

Parameters: update_merch_quantity
NameTypeDescription
item_id required string Item or option ID from list_merch_items.
quantity_available required integer New stock level. 0 marks the item Sold Out.
shipping_origin string Shipping origin to change. Default: your main origin.

tools/call

JSON-RPC 

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "bandcamp_update_merch_quantity",
    "arguments": {
      "item_id": "o_1842702675",
      "quantity_available": 6,
      "shipping_origin": "Tour van"
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "item_id": "p_1154611570",
    "title": "Band Tote",
    "quantity_available": 40,
    "previous_quantity_available": 6
  },
  "isError": false
}

Update release

write Confirm

MCP tool bandcamp_update_release

Changes the price, title or release date of one album or track, like the edit button on its page or the Bulk Edit page. Pass only the fields you want to change. By default you confirm each call; you can switch that off for this tool.

Parameters

Parameters: update_release
NameTypeDescription
release_id required string Album or track ID from list_releases.
price number New price.
title string New title.
release_date date New release date.

tools/call

JSON-RPC 

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "bandcamp_update_release",
    "arguments": {
      "release_id": "release_8c41d2"
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "release_id": "r_1840221",
    "title": "Night Drive",
    "price": 7,
    "currency": "USD",
    "release_date": "2025-11-14",
    "updated": [
      "price"
    ]
  },
  "isError": false
}

Create discount code

write Confirm

MCP tool bandcamp_create_discount_code

Creates a discount code. The percentage applies to the base price of the item, never to shipping or taxes. Codes cannot take a release priced at zero, and 100% off is not offered. If you set expires_on, Bandcamp disables the code on that day. By default you confirm each call; you can switch that off for this tool.

Parameters

Parameters: create_discount_code
NameTypeDescription
name required string The code fans type, e.g. summersale.
percent_off required integer Percent off the base price. 100 is not offered.
applies_to enum anything, anything_except_preorders, digital_only, physical_only or single_item. Default: anything.
item_id string Release or package ID when applies_to is single_item.
expires_on date Bandcamp disables the code on this day.

tools/call

JSON-RPC 

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "bandcamp_create_discount_code",
    "arguments": {
      "name": "NIGHTDRIVE20",
      "percent_off": 20,
      "applies_to": "single_item",
      "item_id": "r_1840221",
      "expires_on": "2026-10-31"
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "code": "summersale",
    "percent_off": 20,
    "applies_to": "single_item",
    "item_id": "r_1840221",
    "expires_on": "2026-08-31",
    "status": "active"
  },
  "isError": false
}

Generate track/album codes

write Confirm

MCP tool bandcamp_generate_track_album_codes

Creates a batch of track/album codes for a release you choose. Codes come in multiples of 100 with a minimum of 100 per batch, never expire, and count against the code allowance shown on your Tools page. The batch name is private to you. By default you confirm each call; you can switch that off for this tool.

Parameters

Parameters: generate_track_album_codes
NameTypeDescription
release_id required string Album or track ID from list_releases.
batch_name required string Private label for the batch, e.g. tour-2026.
count required integer Multiples of 100, at least 100.

tools/call

JSON-RPC 

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "bandcamp_generate_track_album_codes",
    "arguments": {
      "release_id": "release_8c41d2",
      "batch_name": "batch name",
      "count": 20
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "batch_id": "b_0042",
    "batch_name": "tour-2026",
    "release_id": "r_1902254",
    "codes_created": 100
  },
  "isError": false
}

Send Community message

write Confirm

MCP tool bandcamp_send_community_message

Posts a message under your artist name. Fans who follow you receive it by email and in the Bandcamp app, and it appears on your Community page. Fans need to follow you to receive messages and to buy a release before they can comment. By default you confirm each call; you can switch that off for this tool.

Parameters

Parameters: send_community_message
NameTypeDescription
body required string Message text.

tools/call

JSON-RPC 

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "bandcamp_send_community_message",
    "arguments": {
      "body": "body"
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "message_id": "cm_2207",
    "status": "published",
    "published_at": "2026-10-11T10:00:00+02:00"
  },
  "isError": false
}