# etsy-mcp-server

Full-featured [Model Context Protocol](https://modelcontextprotocol.io) server for the [Etsy Open API v3](https://developers.etsy.com/documentation/). Manage your Etsy shop — listings, inventory, images, digital files, orders — entirely through Claude or any MCP-compatible client.

## Features

| Group | Tools |
|-------|-------|
| **Shop** | `get_me`, `get_shop`, `update_shop` |
| **Listings** | `list_listings`, `get_listing`, `create_listing`, `update_listing`, `publish_listing`, `delete_listing` |
| **Images** | `list_listing_images`, `upload_listing_image`, `delete_listing_image` |
| **Digital files** | `list_listing_files`, `upload_listing_file`, `delete_listing_file` |
| **Inventory** | `get_inventory`, `update_inventory` |
| **Sections** | `list_sections`, `create_section`, `update_section`, `delete_section` |
| **Taxonomy** | `get_taxonomy_nodes`, `get_taxonomy_properties`, `suggest_tags` |
| **Orders** | `list_orders`, `get_order` |

## Prerequisites

- Node.js 18+
- An [Etsy Developer account](https://www.etsy.com/developers/register) with an app created
- Your app must be approved for OAuth write access (Etsy reviews new apps)

## Installation

```bash
git clone https://github.com/DColl/etsy-mcp-server.git
cd etsy-mcp-server
npm install
cp .env.example .env
```

Edit `.env` and fill in your credentials:

```env
ETSY_API_KEY=your_keystring_here
ETSY_API_SECRET=your_shared_secret_here
```

## Authentication

### Step 1 — OAuth authorization (required for write operations)

```bash
npm run auth
```

This opens a local browser flow. After authorizing, tokens are saved to `.env` automatically.

### Step 2 — Find your Shop ID

Build the server and ask Claude: `"call get_me"` — it returns your `shop_id`. Add it to `.env`:

```env
ETSY_SHOP_ID=12345678
```

## Build & run

```bash
npm run build
npm start
```

Or in dev mode (no build step):

```bash
npm run dev
```

## Configure Claude Code

Add to your Claude Code settings (`~/.claude/settings.json` or project `.claude/settings.json`):

```json
{
  "mcpServers": {
    "etsy": {
      "command": "node",
      "args": ["/absolute/path/to/etsy-mcp-server/dist/index.js"],
      "env": {
        "ETSY_API_KEY": "your_keystring",
        "ETSY_API_SECRET": "your_shared_secret",
        "ETSY_ACCESS_TOKEN": "your_access_token",
        "ETSY_REFRESH_TOKEN": "your_refresh_token",
        "ETSY_TOKEN_EXPIRY": "your_token_expiry",
        "ETSY_SHOP_ID": "your_shop_id"
      }
    }
  }
}
```

## Configure Claude Desktop

Add to `~/AppData/Roaming/Claude/claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "etsy": {
      "command": "node",
      "args": ["C:\\path\\to\\etsy-mcp-server\\dist\\index.js"]
    }
  }
}
```

## Example usage with Claude

```
Create a draft listing for my PDF printable "STOP Before You Pay" fraud prevention checklist.
Price: $4.99, it's a digital download, quantity 999.
Use suggest_tags with keyword "printable" to find the right taxonomy, then add tags.
Upload cover.jpg as image and stop-before-you-pay.pdf as the digital file.
Then publish the listing.
```

## Rate limits

Etsy allows 5 requests/second and 5,000 requests/day per API key.

## License

MIT — © TBS-Digital 2026