etsy-mcp
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.
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
vintageim 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 |
| Stichwortsuche in aktiven Angeboten, optional shop-bezogen. |
| Abrufen eines Angebots nach ID. |
| Abrufen des Shop-Datensatzes (Name, Währung, Anzahl, Urlaub). |
| Auflisten von Belegen (Bestellungen) in einem Datumsfenster für einen Shop. |
| Abrufen eines Belegs nach ID, einschließlich der Transaktionsposten. |
| Inventar auf Varianten-Ebene (SKU, Menge, Preis) für ein Angebot. |
| Zusammengefasste Perioden-Auswertung: Bestellungen, Favoriten, Umsatz, Angebote. |
| 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-mcpv0.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-mcpoder klonen Sie es und führen Siepip 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 # optionalEinen Etsy-API-Schlüssel erhalten
Besuchen Sie https://www.etsy.com/developers/your-apps und registrieren Sie eine App.
Kopieren Sie den Keystring – das ist
ETSY_API_KEY.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=codeclient_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>undcode_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, ~3sPre-Commit-Hooks (gitleaks, trufflehog, ruff, formatter, Tenant-Fingerprint-Scrubber):
pip install pre-commit
pre-commit installIntegrationstests 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
pytestaus, bevor Sie einen PR öffnen (pip install -e ".[dev]").Führen Sie
pre-commit run --all-filesaus.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 toolsetsy_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
Scored across 8 tools
Each tool targets a distinct resource (listings, inventory, shop, orders) and operation (get, search, stats), with no overlapping purposes.
All tools follow the consistent pattern 'etsy_<verb>_<noun>', using snake_case and clear verbs (get, search) throughout.
8 tools is reasonable for an Etsy API wrapper, covering key read operations without being excessive.
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
Related MCP Connectors
Hosted Amazon Seller Central and Amazon Ads MCP server for Claude, ChatGPT, Cursor, and agents.
Hosted MCP server for 3Dsellers, the multichannel selling platform. Connect Claude, ChatGPT, Cursor, VS Code or any MCP client and manage your eBay, Amazon, Walmart, Etsy, Shopify, WooCommerce and TikTok Shop stores in plain language: search and update products, publish listings, sync inventory, tag and track orders, run bulk actions and CSV imports, and reply to customer messages. 120+ tools. Sign in with OAuth or a personal token. No eBay developer account and nothing to install. Setup guides and config examples for every client: https://github.com/3dsellers/ebay-mcp-server
Hosted Amazon Seller and Vendor MCP server for Claude, ChatGPT, Cursor, Codex, Gemini, Copilot.
Hosted MCP server to manage a restaurant menu from AI agents - 39 tools over the DuckHub API.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceThis is a deployable remote MCP server that lets OpenAI Agent Builder connect directly to Etsy using Etsy OAuth 2.0 with PKCE.-
- AlicenseCqualityDmaintenanceComprehensive MCP server for the Etsy API v3, providing 50+ tools to manage listings, shops, orders, payments, and more through natural language.1004MIT
- AlicenseAqualityDmaintenanceA 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.262MIT
- FlicenseNot gradedqualityDmaintenanceA 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.-