Skip to main content
Glama

etsy-mcp

Der erste produktionsreife Model Context Protocol-Server für Etsy. Verbinden Sie Claude in fünf Minuten mit den Angeboten, dem Inventar, den Bestellungen und den Statistiken Ihres Etsy-Shops – schreibgeschützt.

License: MIT Python 3.10+ MCP

Warum gibt es das?

Etsys Open API v3 ist gut dokumentiert und stabil, aber jeder Verkäufer, der ein LLM für seinen Shop nutzen möchte, schreibt am Ende die gleiche OAuth- und Paginierungs-Logik von Grund auf neu. Bestehende MCP-Integrationen sind oft nur einfache Demos, denen Token-Aktualisierung, Wiederholungslogik und die pro Shop erforderliche Paginierung fehlen.

Wenn Sie auf Etsy verkaufen und sich schon immer gewünscht haben, dass Claude (oder ein anderer MCP-fähiger KI-Assistent) einfach weiß, was in Ihrem Shop passiert – was gelistet ist, was gestern versandt wurde, was knapp wird –, dann ist diese Lücke der Unterschied zwischen „Summarize today's orders“ (funktioniert sofort) und „Summarize today's orders“ (erfordert eine benutzerdefinierte Integration).

etsy-mcp schließt diese Lücke. Es ist ein kleiner, gut getesteter, unter der MIT-Lizenz stehender MCP-Server, der acht schreibgeschützte Etsy-Endpunkte für jeden MCP-Client bereitstellt. Entwickelt aus jahrelanger Erfahrung mit der Skalierung von E-Commerce-Automatisierung im Produktionsbetrieb.

Related MCP server: @mcpengine/etsy

Was Sie damit tun können

Verbinden Sie diesen Server mit Claude Code, Claude Desktop oder einem beliebigen MCP-Host und stellen Sie Fragen wie:

  • „Suche in meinem Shop nach Angeboten mit dem Wort vintage im Titel und sage mir, wie viele davon einen Bestand von unter 5 haben.“

  • „Wie viele Bestellungen habe ich gestern erhalten? Gruppiere sie nach Käufer und Gesamtumsatz.“

  • „Rufe Beleg 5550001 ab und sage mir, welche Transaktionen versandt wurden – und was noch versandt werden muss.“

  • „Wie waren meine Shop-Statistiken in den letzten 30 Tagen? Vergleiche Bestellungen, Favoriten und aktive Angebote.“

  • „Zeige mir für Angebot 1234567890 jede Variante, deren SKU und den aktuellen Bestand.“

Claude liest Ihren Shop direkt. Kein Kopieren und Einfügen, keine Tabellenkalkulationen, keine benutzerdefinierten Pipelines.

Tools (v0.1, alle schreibgeschützt)

Tool

Was es tut

etsy_search_listings

Stichwortsuche in aktiven Angeboten, optional shop-bezogen.

etsy_get_listing

Abrufen eines Angebots nach ID.

etsy_get_shop

Abrufen des Shop-Datensatzes (Name, Währung, Anzahl, Urlaub).

etsy_search_orders

Auflisten von Belegen (Bestellungen) in einem Datumsfenster für einen Shop.

etsy_get_order

Abrufen eines Belegs nach ID, einschließlich der Transaktionsposten.

etsy_get_inventory

Inventar auf Varianten-Ebene (SKU, Menge, Preis) für ein Angebot.

etsy_get_shop_stats

Zusammengefasste Perioden-Auswertung: Bestellungen, Favoriten, Umsatz, Angebote.

etsy_get_active_listings

Paginierte Liste aller aktiven Angebote in einem Shop.

Schreib-Endpunkte (Entwurfsangebot erstellen, Inventar aktualisieren, Beleg als versandt markieren) sind in v0.1 absichtlich nicht enthalten. Sie sind für v0.2 geplant, sobald sich die Ergonomie der Lese-Tools gefestigt hat.

Installation

pip install etsy-mcp

v0.1 wird aus diesem Repository bereitgestellt. Die Veröffentlichung auf PyPI steht noch aus – installieren Sie es vorerst mit pip install git+https://github.com/alveyautomation/etsy-mcp oder klonen Sie es und führen Sie pip install -e . lokal aus.

Anmeldedaten konfigurieren

Der Server liest alles aus Umgebungsvariablen. Kopieren Sie .env.example nach .env und tragen Sie Ihren Tenant ein:

ETSY_API_URL=https://api.etsy.com/v3/application/   # default; usually leave alone
ETSY_API_KEY=your-keystring-from-etsy-developers
ETSY_REFRESH_TOKEN=oauth2-refresh-token-for-your-shop
ETSY_DEFAULT_SHOP_ID=                               # optional fallback
ETSY_HTTP_TIMEOUT=60                                # optional, seconds
ETSY_MAX_RETRIES=3                                  # optional

Einen Etsy-API-Schlüssel erhalten

  1. Besuchen Sie https://www.etsy.com/developers/your-apps und registrieren Sie eine App.

  2. Kopieren Sie den Keystring – das ist ETSY_API_KEY.

  3. Konfigurieren Sie den Redirect-URI für Ihren einmaligen OAuth-Bootstrap (z. B. http://localhost:3000/callback).

Ein Refresh-Token erhalten

Etsy verwendet OAuth 2.0 mit PKCE. Um den Prozess zu starten, führen Sie einmalig einen Standard OAuth-PKCE-Flow mit diesen Parametern aus:

  • response_type=code

  • client_id=<Ihr Keystring>

  • redirect_uri=<Ihr registrierter URI>

  • scope=listings_r shops_r transactions_r (schreibgeschützt – das Minimum, das dieser Server benötigt)

  • state=<zufällig>

  • code_challenge=<PKCE> und code_challenge_method=S256

Tauschen Sie den resultierenden Autorisierungscode unter POST https://api.etsy.com/v3/public/oauth/token gegen ein Zugriffs- + Refresh-Token ein. Speichern Sie das Refresh-Token als ETSY_REFRESH_TOKEN. Der Server verwendet es, um automatisch kurzlebige Zugriffstoken zu erstellen.

Verwenden Sie Lese-Token mit minimalem Umfang. v0.1 ruft nur GET-Endpunkte auf, aber Defense-in-Depth bedeutet, dass Sie dem Refresh-Token des Servers niemals Schreibberechtigungen (*_w) erteilen sollten. Wenn v0.2 mit Schreib-Tools erscheint, aktivieren Sie diese durch das Erstellen eines neuen Tokens mit höherem Umfang – niemals umgekehrt.

In Claude Code einbinden

Fügen Sie dies zu ~/.claude/claude_code_config.json (oder der MCP-Konfiguration Ihres Projekts) hinzu:

{
  "mcpServers": {
    "etsy": {
      "command": "etsy-mcp",
      "env": {
        "ETSY_API_KEY": "your-keystring",
        "ETSY_REFRESH_TOKEN": "your-refresh-token",
        "ETSY_DEFAULT_SHOP_ID": "12345678"
      }
    }
  }
}

Starten Sie Claude Code neu. Die acht etsy_*-Tools erscheinen in jeder neuen Sitzung.

In Claude Desktop einbinden

Bearbeiten Sie ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) oder %APPDATA%\Claude\claude_desktop_config.json (Windows) und fügen Sie denselben mcpServers-Block wie oben hinzu. Starten Sie die Desktop-App neu.

Tool-Referenz

Jedes Tool gibt einen JSON-Umschlag zurück:

{ "ok": true,  "data": { ... } }
{ "ok": false, "error": "human-readable message" }

etsy_search_listings

etsy_search_listings(
    query: str,                          # required
    shop_id: int | None = None,          # scope to a single shop
    limit: int = 50,                     # max 100 (Etsy server cap)
)

Wenn shop_id angegeben ist, greift dies auf /shops/{shop_id}/listings/active zu. Andernfalls greift es auf den globalen /listings/active-Index zu.

etsy_get_listing

etsy_get_listing(listing_id: int)

Gibt den Angebotsdatensatz zurück oder data: null bei 404.

etsy_get_shop

etsy_get_shop(shop_id: int)

Der Shop-Datensatz enthält shop_name, currency_code, listing_active_count, num_favorers, is_vacation und mehr.

etsy_search_orders

etsy_search_orders(
    date_from: str,                      # ISO date "YYYY-MM-DD"
    date_to: str,                        # ISO date "YYYY-MM-DD"
    shop_id: int | None = None,          # falls back to default
    status: str | None = None,           # 'open' | 'unshipped' | 'completed' | 'all'
    limit: int = 200,                    # max 1000
)

Etsy begrenzt die Seitengröße auf 100; die Paginierung erfolgt transparent. Die Antwort enthält limit_reached: true, wenn limit der Punkt der Kürzung war.

etsy_get_order

etsy_get_order(receipt_id: int, shop_id: int | None = None)

Gibt den vollständigen Beleg (mit transactions[]) zurück oder data: null bei 404.

etsy_get_inventory

etsy_get_inventory(listing_id: int)

Gibt products[] mit sku, property_values und offerings[] (Menge, Preis, aktiviert) zurück. Verwenden Sie die Angebotsmenge als kanonische „Verkaufsmenge“ pro Variante.

etsy_get_shop_stats

etsy_get_shop_stats(shop_id: int, period: str = "30d")

Eine zusammengesetzte Auswertung. Etsy bietet in v3 keinen erstklassigen shop/stats-Endpunkt, daher synthetisiert dieser eine aus dem Shop-Datensatz (Favoriten, Anzahl aktiver Angebote) und den Belegen im Zeitraum. Zurückgegebene Form:

{
  "shop_id": 12345678,
  "period": "30d",
  "period_days": 30,
  "date_from": "2026-03-27",
  "date_to": "2026-04-26",
  "favorers": 314,
  "active_listings": 87,
  "orders": 42,
  "revenue_minor_units": 152400,
  "currency_code": "USD"
}

period akzeptiert das Format <N>d, maximal 365 Tage.

etsy_get_active_listings

etsy_get_active_listings(shop_id: int, limit: int = 200)

Paginierter Dump aller aktiven Angebote in einem Shop. Nützlich für katalogweite Analysen („Überprüfe meine Titel auf fehlende Schlüsselwörter“). Das Soft-Limit liegt bei 1000, um einen Tool-Aufruf begrenzt zu halten.

Lokale Entwicklung

git clone https://github.com/alveyautomation/etsy-mcp
cd etsy-mcp
python -m venv .venv && source .venv/bin/activate    # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
pytest                                                # 49 tests, ~3s

Pre-Commit-Hooks (gitleaks, trufflehog, ruff, formatter, Tenant-Fingerprint-Scrubber):

pip install pre-commit
pre-commit install

Integrationstests gegen eine echte Etsy-Sandbox sind hinter ETSY_INTEGRATION_TESTS=1 geschützt. Sie sind für normale Beiträge nicht erforderlich.

Fehlerbehebung

Failed to refresh Etsy access token – Ihr Refresh-Token ist abgelaufen oder wurde widerrufen. Etsy-Refresh-Token sind ab Ausstellung 90 Tage gültig, aber nur, wenn sie regelmäßig verwendet werden. Führen Sie den OAuth-PKCE-Bootstrap erneut aus, um ein neues zu erstellen.

Missing required environment variables – der Server versuchte zu starten, bevor seine .env geladen wurde. Exportieren Sie die Variablen entweder in der übergeordneten Shell oder stellen Sie sicher, dass Ihre MCP-Host-Konfiguration sie im env-Block enthält.

HTTP 403 bei Belegen/Transaktionen – den Scopes des Refresh-Tokens fehlt transactions_r. Führen Sie den Bootstrap erneut mit den oben aufgeführten Lese-Scopes durch.

Leere Ergebnisse trotz bekannter Daten – bestätigen Sie die shop_id. Die /shops/{shop_id}/...-Endpunkte von Etsy geben nur Daten für Shops zurück, für die das OAuth-Token autorisiert wurde.

Paginierung fühlt sich langsam an – Etsy begrenzt die Seitengröße auf 100 pro Anfrage, nicht wir. Erwarten Sie bei großen Zeiträumen (lange Bestellhistorien) mehrere Roundtrips. Verringern Sie das limit-Argument, um den Aufruf zu begrenzen.

Mitwirken

Probleme und Pull Requests sind willkommen. Bitte:

  • Führen Sie pytest aus, bevor Sie einen PR öffnen (pip install -e ".[dev]").

  • Führen Sie pre-commit run --all-files aus.

  • Halten Sie Ergänzungen im v0.1-Umfang schreibgeschützt. Schreib-Endpunkte kommen in v0.2.

  • Nur synthetische Daten in Tests – keine echten Shop-Namen, Angebots-IDs oder Belegnummern.

Lizenz

MIT – siehe LICENSE.

Haftungsausschluss

etsy-mcp ist eine inoffizielle Integration eines Drittanbieters. Sie wird nicht von Etsy, Inc. unterstützt, ist nicht mit Etsy, Inc. verbunden und wird nicht von Etsy, Inc. gefördert. „Etsy“ ist eine Marke von Etsy, Inc. Verwendung auf eigenes Risiko; überprüfen Sie das Verhalten in Ihrem Shop, bevor Sie sich für produktionsrelevante Entscheidungen darauf verlassen.

Available Tools

8 tools
etsy_get_active_listingsA

List active listings for a shop, paginating transparently.

Args: shop_id: Etsy ShopID. limit: Soft cap on yielded listings (default 200, max 1000).

Returns: JSON envelope. data.listings is the list of active-listing records.

Inputs: shop_id (required), limit. Returns: result

etsy_get_inventoryA

Fetch the current inventory record (variations + offerings) for a listing.

Args: listing_id: Etsy ListingID.

Returns: JSON envelope. data is the inventory record (with products[] carrying property values, SKU, price, and offerings[] with quantity), or null if absent.

Inputs: listing_id (required). Returns: result

etsy_get_listingA

Fetch the full record for a single listing.

Args: listing_id: Etsy ListingID (integer).

Returns: JSON envelope. data is the listing record, or null if not found.

Inputs: listing_id (required). Returns: result

etsy_get_orderB

Fetch full receipt (order) detail including transactions.

Args: receipt_id: Etsy ReceiptID (integer). shop_id: Etsy ShopID. Falls back to ETSY_DEFAULT_SHOP_ID if omitted.

Returns: JSON envelope. data is the receipt record, or null if missing.

Inputs: receipt_id (required), shop_id. Returns: result

etsy_get_shopA

Fetch the shop record for a single shop.

Args: shop_id: Etsy ShopID (integer).

Returns: JSON envelope. data is the shop record (with name, currency_code, listing_active_count, num_favorers, etc.), or null if not found.

Inputs: shop_id (required). Returns: result

etsy_get_shop_statsA

Return aggregated stats (orders, favorers, active listings, revenue) for a shop over the given period.

Args: shop_id: Etsy ShopID. period: Lookback window in the form 'd', e.g. '7d', '30d', '90d'. Maximum 365 days.

Returns: JSON envelope. data is a dict with orders, favorers, active_listings, revenue_minor_units, currency_code, and the resolved date_from / date_to.

Inputs: shop_id (required), period. Returns: result

etsy_search_listingsA

Search active Etsy listings by keyword.

Args: query: Free-text keyword search across listing title and tags. shop_id: Optional Etsy ShopID to scope the search to a single shop. When omitted, queries the global active-listings index. limit: Cap on returned results (max 100 enforced by Etsy).

Returns: JSON envelope: {"ok": true, "data": {"results": [...], "count": N}}.

Inputs: query (required), shop_id, limit. Returns: result

etsy_search_ordersA

Search receipts (orders) created in the inclusive [date_from, date_to] window for a shop.

Args: date_from: ISO date (YYYY-MM-DD), start of window. date_to: ISO date (YYYY-MM-DD), end of window. shop_id: Etsy ShopID to scope the search to. Falls back to ETSY_DEFAULT_SHOP_ID if omitted. status: Optional receipt status filter ('open', 'unshipped', 'unpaid', 'completed', 'processing', 'all'). limit: Cap on yielded receipts (default 200, max 1000). Etsy caps page size at 100 per request; pagination is handled transparently.

Returns: JSON envelope. data.orders is the list of receipt records.

Inputs: date_from (required), date_to (required), shop_id, status, +1 more. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 8 tools

    Disambiguation5/5

    Each tool targets a distinct resource (listings, inventory, shop, orders) and operation (get, search, stats), with no overlapping purposes.

    Naming Consistency5/5

    All tools follow the consistent pattern 'etsy_<verb>_<noun>', using snake_case and clear verbs (get, search) throughout.

    Tool Count4/5

    8 tools is reasonable for an Etsy API wrapper, covering key read operations without being excessive.

    Completeness2/5

    The server provides only read/search operations; missing critical mutation tools like create/update/delete listing or update order, leaving significant gaps for full lifecycle management.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      A full-featured MCP server for the Etsy Open API v3 that enables managing an Etsy shop, including listings, inventory, images, digital files, and orders, through Claude or any MCP-compatible client.
      26
      2
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      A custom MCP server exposing database, ticketing, and external-API tools to both Claude Desktop and a self-built autonomous agent powered by Groq's free-tier LLaMA 3.3.
      -