etsy-api

A stdio MCP server that wraps the Etsy Open API v3 (all 103 operations), generated from 3.0.0.json. Built with the official TypeScript MCP SDK, for a single Etsy shop owner. Published on npm as etsy-api — run it with npx -y etsy-api.

Tools

The full API surface is exposed through two generic tools, plus a handful of promoted named tools for everyday tasks so common actions don't need a discovery step.

| Tool | Purpose | |---|---| | etsy_search_actions | Search all 103 operations by intent → returns operationIds + schemas | | etsy_execute_action | Run any operation by operationId with a flat params object | | etsy_get_me, etsy_get_shop, etsy_get_listings_by_shop, etsy_get_listing, etsy_create_draft_listing, etsy_update_listing, etsy_get_shop_receipts, etsy_get_listing_inventory | Promoted shortcuts |

Typical flow: ask etsy_search_actions("mark order as shipped"), take the returned operationId, then call etsy_execute_action with it.

Install

The server is published to npm and runs over stdio. The easiest path is to let your MCP host launch it on demand with npx (see Register with Claude) — no manual install needed.

To run from a local checkout instead:

npm install      # builds to dist/ via the prepare script
npm start        # needs ETSY_API_KEY in env

Credentials

The server reads three environment variables (passed via the MCP host's env block):

| Variable | Required | Notes | |---|---|---| | ETSY_API_KEY | yes | Your app keystring, sent as the x-api-key header. (Etsy documents it as keystring:shared_secret; the keystring alone also works.) | | ETSY_ACCESS_TOKEN | for authenticated calls | OAuth2 access token, sent as Authorization: Bearer. Expires ~1 hour after issue. | | ETSY_REFRESH_TOKEN | recommended | If present, the server auto-refreshes the access token when it expires (refresh tokens last ~90 days). |

• 32 operations (e.g. getListing, taxonomy lookups) need only ETSY_API_KEY.
• 71 operations need a user OAuth token with the right per-operation scope; each tool reads its own required scope from the spec.

Register with your agent

This is a standard stdio MCP server, so any MCP-capable agent can run it. The shape is the same everywhere — launch npx -y etsy-api and pass the three Etsy env vars. Pick your client below.

Prerequisite: Node.js 20+ on PATH (provides npx). Windows: if npx isn't found, set "command": "cmd" and "args": ["/c", "npx", "-y", "etsy-api"]. Local checkout instead of npm? Swap the command for "node" with args ["/absolute/path/to/etsy-api/dist/index.js"].

The env block is identical for every client:

"env": {
  "ETSY_API_KEY": "<your keystring>",
  "ETSY_ACCESS_TOKEN": "<oauth access token>",
  "ETSY_REFRESH_TOKEN": "<oauth refresh token>"
}

Claude Code

claude mcp add etsy \
  --env ETSY_API_KEY=<your keystring> \
  --env ETSY_ACCESS_TOKEN=<oauth access token> \
  --env ETSY_REFRESH_TOKEN=<oauth refresh token> \
  -- npx -y etsy-api

Add --scope project to write a shared .mcp.json in the repo instead of your user config. Verify with claude mcp list.

Claude Desktop

Edit claude_desktop_config.json (Settings → Developer → Edit Config, or ~/Library/Application Support/Claude/ on macOS, %APPDATA%\Claude\ on Windows), then restart the app:

{
  "mcpServers": {
    "etsy": {
      "command": "npx",
      "args": ["-y", "etsy-api"],
      "env": { "ETSY_API_KEY": "...", "ETSY_ACCESS_TOKEN": "...", "ETSY_REFRESH_TOKEN": "..." }
    }
  }
}

Cursor

Create .cursor/mcp.json in your project (or ~/.cursor/mcp.json for all projects). Same mcpServers schema as Claude Desktop above. Enable it under Settings → MCP.

Windsurf

Edit ~/.codeium/windsurf/mcp_config.json (Settings → Cascade → MCP Servers → Manage). Same mcpServers schema as Claude Desktop above; click refresh after saving.

VS Code (GitHub Copilot Agent mode)

Create .vscode/mcp.json. Note VS Code uses servers (not mcpServers) and a type field:

{
  "servers": {
    "etsy": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "etsy-api"],
      "env": { "ETSY_API_KEY": "...", "ETSY_ACCESS_TOKEN": "...", "ETSY_REFRESH_TOKEN": "..." }
    }
  }
}

Or run code --add-mcp '{"name":"etsy","command":"npx","args":["-y","etsy-api"]}' and add env in the UI.

Cline / Roo Code (VS Code extensions)

Open the extension's MCP Servers → Configure panel (writes cline_mcp_settings.json). Same mcpServers schema as Claude Desktop above.

Zed

In settings.json, Zed uses context_servers:

{
  "context_servers": {
    "etsy": {
      "command": { "path": "npx", "args": ["-y", "etsy-api"] },
      "env": { "ETSY_API_KEY": "...", "ETSY_ACCESS_TOKEN": "...", "ETSY_REFRESH_TOKEN": "..." }
    }
  }
}

Any other MCP client

Run the binary directly over stdio with the three env vars set:

ETSY_API_KEY=... ETSY_ACCESS_TOKEN=... ETSY_REFRESH_TOKEN=... npx -y etsy-api

Architecture

src/
  index.ts    MCP server entry (stdio)
  config.ts   env → Config
  catalog.ts  parse 3.0.0.json → Operation[] (method, path, params, scopes, body)
  http.ts     EtsyClient: request building, auth headers, token auto-refresh
  tools.ts    search_actions + execute_action + promoted tools
3.0.0.json    Etsy Open API v3 spec (source of truth)

The catalog is generated from the spec at startup, so updating 3.0.0.json and rebuilding keeps every tool in sync. Request bodies are encoded per the spec (x-www-form-urlencoded, application/json, or multipart/form-data for uploads).

Notes / roadmap

• Multipart uploads (uploadListingImage, etc.) accept a local file_path; the upload field defaults to image.
• The interactive OAuth authorization-code + PKCE flow isn't included yet — tokens are supplied via env. A npm run auth command can be added when you can run the full login.