etsy-mcp

Professional-grade Model Context Protocol server wrapping the Etsy Open API v3 as pure capability primitives. Built so AI agents (Claude, ChatGPT, Gemini, local Llama) can manage Etsy shops at scale without baked-in heuristics getting in their way.

What this is

90 tools across 13 categories — every endpoint your agent needs to:

• Read shops, listings, listing images/videos/inventory/properties/translations/digital files

• Manage receipts, payments, shipping profiles

• Walk the seller taxonomy and read reviews

• Look up users and buyer addresses

• Bulk create / update listings from templates (rate-limit-friendly)

• Bulk update image alt_text across an entire shop

Every tool is a thin wrapper around an Etsy API endpoint. No scoring algorithms. No SEO heuristics. No tag generators. No "AI search readiness" judgments. The MCP is a capability layer; your model is the reasoning layer.

Related MCP server: Etsy MCP Server

Why pure primitives

A baked-in seo_score_listing heuristic goes stale the day it ships. AI ranking algorithms change constantly, and Claude/GPT/Gemini/Llama all reason differently about SEO. By keeping every judgment inside the model, the MCP works identically across every agent today and continues to work as both Etsy's algorithms and your model evolve. Less code, lower test surface, no hidden intelligence to debug. See docs/WORKFLOWS.md for end-to-end LLM-driven workflow examples that prove the model alone is enough.

How we compare

Quick start

Install

uvx etsy-mcp@latest --help

Or install into a project:

uv add etsy-mcp

Authenticate

For shared n8n/MCP authentication, configure the private Etsy token service:

ETSY_KEYSTRING=your_etsy_app_keystring
ETSY_SHARED_SECRET=your_etsy_app_shared_secret
ETSY_BROKER_URL=http://etsy-token:8080
ETSY_BROKER_KEY=the_token_services_client_keys_mcp_value

Pass these variables to the MCP process. From this checkout, run uv run --package etsy-mcp etsy-mcp auth info to inspect the service. MCP ignores local tokens in this mode; only the service refreshes them. See docs/TOKEN_SERVICE.md for migration and Docker/host setup. Run this checkout containing the change; the upstream PyPI package does not automatically include changes from this fork.

For standalone authentication without broker variables:

etsy-mcp auth login

This walks you through the OAuth 2.0 + PKCE flow, opens your browser, captures the callback on localhost:3456, and writes tokens to ~/.config/etsy-mcp/tokens.json (mode 0600). Refresh tokens rotate automatically; you only re-auth if your refresh token is invalidated.

Register with Claude Code

claude mcp add etsy -- uvx etsy-mcp@latest

Or in claude_desktop_config.json:

{
  "mcpServers": {
    "etsy": {
      "command": "uvx",
      "args": ["etsy-mcp@latest"],
      "env": {
        "ETSY_KEYSTRING": "your-app-keystring",
        "ETSY_SHARED_SECRET": "your-app-shared-secret"
      }
    }
  }
}

Remote Docker deployment

This fork supports both local stdio and long-running Streamable HTTP transport. The included Docker Compose file runs the MCP server continuously while keeping the host port loopback-only by default:

docker compose build
docker compose up -d
docker compose logs -f etsy-mcp

The MCP endpoint is then:

http://127.0.0.1:8000/mcp

Put an authenticated HTTPS reverse proxy in front of that endpoint for remote clients. Do not expose the container port directly to the public internet. The MCP container joins the external etsy-auth Docker network and reaches the shared token service at http://etsy-token:8080.

Local stdio remains the default:

uv run --package etsy-mcp etsy-mcp

You can also select Streamable HTTP explicitly without Docker:

uv run --package etsy-mcp etsy-mcp serve \
  --transport streamable-http \
  --host 127.0.0.1 \
  --port 8000 \
  --path /mcp

Configuration

Either broker variable selects broker mode; incomplete configuration fails instead of using local OAuth. See .env.example for other server settings.

Documentation

• docs/ARCHITECTURE.md — package layering and responsibilities

• docs/OAUTH.md — full PKCE flow and token rotation

• docs/TOKEN_SERVICE.md — shared n8n/MCP token-service authentication

• docs/RATE_LIMITS.md — token bucket, daily counter, backoff

• docs/ERROR_HANDLING.md — exception hierarchy and envelope shapes

• docs/TESTING.md — unit and integration test strategy

• docs/WORKFLOWS.md — end-to-end LLM workflows using only primitives

• docs/permissions.md — policy gates and confirmation modes

• SECURITY.md, PRIVACY.md

Security notice

In token-service mode, refresh tokens stay on the private service; MCP obtains access tokens in memory and never falls back to local OAuth. In standalone mode, tokens are stored at ~/.config/etsy-mcp/tokens.json with mode 0600, and the latest refresh response is persisted. The F3 redaction layer scrubs OAuth tokens, broker keys, buyer PII and shop credentials. Report vulnerabilities per SECURITY.md — never via public issues.

Contributing

See CONTRIBUTING.md for the development workflow, golden paths, and PR conventions. The full project rules live in AGENTS.md — read them before opening a PR.

License

MIT — copyright 2026 Rick Villucci