# Bandcamp MCP tools

> Every Bandcamp MCP tool on the Cotlet server: tool names, input schemas, a tools/call example and an example result for each tool.

Source: https://cotlet.dev/docs/mcp/bandcamp

Docs sections: [Get started](https://cotlet.dev/docs.md) · [REST API](https://cotlet.dev/docs/api.md) · [MCP](https://cotlet.dev/docs/mcp.md) · [SDKs & CLI](https://cotlet.dev/docs/sdks.md) · [Integrations](https://cotlet.dev/docs/integrations.md)

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: https://cotlet.dev/integrations/bandcamp-api-mcp-server

## 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

MCP tool: `bandcamp_list_releases`

Access: read.

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

| Name | Type | Required | Description |
|---|---|---|---|
| `format` | enum | no | digital, physical or all. Default: all. |
| `visibility` | enum | no | public, private, draft or all. Default: all. |

### tools/call

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

### Example response

```json
{
  "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

MCP tool: `bandcamp_list_sales`

Access: read.

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

| Name | Type | Required | Description |
|---|---|---|---|
| `since` | date | no | Start of the date range. Default: 30 days ago. |
| `until` | date | no | End of the date range. Default: today. |

### tools/call

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

### Example response

```json
{
  "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

MCP tool: `bandcamp_export_sales_report`

Access: read.

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

| Name | Type | Required | Description |
|---|---|---|---|
| `report` | enum | yes | revenue_summary, payout_statement or raw_data. |
| `since` | date | no | Start of the date range. Default: 30 days ago. |
| `until` | date | no | End of the date range. Default: today. |
| `release_id` | string | no | revenue_summary only: limit the report to this release. |

### tools/call

```json
{
  "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

```json
{
  "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

MCP tool: `bandcamp_list_merch_orders`

Access: read.

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

| Name | Type | Required | Description |
|---|---|---|---|
| `unshipped_only` | boolean | no | Only orders not marked shipped. Default: true. |
| `search` | string | no | Buyer email, last name or Bandcamp payment ID. |
| `since` | date | no | Start of the date range. Default: 30 days ago. |
| `until` | date | no | End of the date range. Default: today. |

### tools/call

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

### Example response

```json
{
  "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

MCP tool: `bandcamp_list_merch_items`

Access: read.

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

| Name | Type | Required | Description |
|---|---|---|---|
| `low_stock_below` | integer | no | Only items with fewer available than this. |

### tools/call

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

### Example response

```json
{
  "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

MCP tool: `bandcamp_list_track_album_codes`

Access: read.

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

| Name | Type | Required | Description |
|---|---|---|---|
| `batch_id` | string | no | Batch ID from a previous call. Returns the codes of this batch. |

### tools/call

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

### Example response

```json
{
  "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

MCP tool: `bandcamp_mark_order_shipped`

Access: write. Confirm: waits for the user's OK before it runs.

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

| Name | Type | Required | Description |
|---|---|---|---|
| `order_id` | string | yes | Order ID from list_merch_orders. |
| `tracking_number` | string | no | Tracking number shown to the buyer. |
| `note` | string | no | Note for the buyer in the shipping email. |

### tools/call

```json
{
  "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

```json
{
  "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

MCP tool: `bandcamp_refund_merch_order`

Access: write. Confirm: waits for the user's OK before it runs.

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

| Name | Type | Required | Description |
|---|---|---|---|
| `order_id` | string | yes | Order ID from list_merch_orders. |
| `return_to_stock` | boolean | no | Put the item back into your inventory. Default: false. |

### tools/call

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

### Example response

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

## Update merch quantity

MCP tool: `bandcamp_update_merch_quantity`

Access: write.

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

| Name | Type | Required | Description |
|---|---|---|---|
| `item_id` | string | yes | Item or option ID from list_merch_items. |
| `quantity_available` | integer | yes | New stock level. 0 marks the item Sold Out. |
| `shipping_origin` | string | no | Shipping origin to change. Default: your main origin. |

### tools/call

```json
{
  "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

```json
{
  "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

MCP tool: `bandcamp_update_release`

Access: write. Confirm: waits for the user's OK before it runs.

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

| Name | Type | Required | Description |
|---|---|---|---|
| `release_id` | string | yes | Album or track ID from list_releases. |
| `price` | number | no | New price. |
| `title` | string | no | New title. |
| `release_date` | date | no | New release date. |

### tools/call

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

### Example response

```json
{
  "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

MCP tool: `bandcamp_create_discount_code`

Access: write. Confirm: waits for the user's OK before it runs.

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

| Name | Type | Required | Description |
|---|---|---|---|
| `name` | string | yes | The code fans type, e.g. summersale. |
| `percent_off` | integer | yes | Percent off the base price. 100 is not offered. |
| `applies_to` | enum | no | anything, anything_except_preorders, digital_only, physical_only or single_item. Default: anything. |
| `item_id` | string | no | Release or package ID when applies_to is single_item. |
| `expires_on` | date | no | Bandcamp disables the code on this day. |

### tools/call

```json
{
  "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

```json
{
  "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

MCP tool: `bandcamp_generate_track_album_codes`

Access: write. Confirm: waits for the user's OK before it runs.

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

| Name | Type | Required | Description |
|---|---|---|---|
| `release_id` | string | yes | Album or track ID from list_releases. |
| `batch_name` | string | yes | Private label for the batch, e.g. tour-2026. |
| `count` | integer | yes | Multiples of 100, at least 100. |

### tools/call

```json
{
  "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

```json
{
  "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

MCP tool: `bandcamp_send_community_message`

Access: write. Confirm: waits for the user's OK before it runs.

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

| Name | Type | Required | Description |
|---|---|---|---|
| `body` | string | yes | Message text. |

### tools/call

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

### Example response

```json
{
  "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
}
```