de en es ja ko ru zh

etsy-mcp

Name: etsy-mcp
Author: alveyautomation

by alveyautomation

Overview Schema Source Related Servers Discussions Admin

Python

Remote

etsy-mcp

Первый сервер Model Context Protocol промышленного уровня для Etsy. Подключите Claude к товарам, инвентарю, заказам и статистике вашего магазина Etsy — только для чтения, за пять минут.

License: MIT Python 3.10+ MCP

Зачем это нужно

Open API v3 от Etsy хорошо задокументирован и стабилен, но каждый продавец, желающий использовать LLM для своего магазина, в итоге пишет один и тот же код для OAuth и пагинации с нуля. Существующие интеграции MCP — это лишь поверхностные демо-версии, в которых отсутствуют обновление токенов, логика повторных попыток и пагинация для каждого магазина, которая на самом деле требуется Etsy.

Если вы продаете на Etsy и когда-либо хотели, чтобы Claude (или любой другой ИИ-ассистент с поддержкой MCP) просто знал, что находится в вашем магазине — что выставлено на продажу, что было отправлено вчера, что заканчивается на складе — то этот разрыв и есть разница между тем, как «обобщить сегодняшние заказы» работает «из коробки», и тем, как для этого требуется специальная интеграция.

etsy-mcp устраняет этот разрыв. Это компактный, хорошо протестированный сервер MCP с лицензией MIT, который предоставляет восемь эндпоинтов Etsy только для чтения любому клиенту MCP. Создан на основе многолетнего опыта автоматизации электронной коммерции промышленного масштаба.

Related MCP server: @mcpengine/etsy

Что можно делать с помощью этого сервера

Подключите этот сервер к Claude Code, Claude Desktop или любому другому хосту MCP, а затем задавайте вопросы, например:

«Найди в моем магазине все товары со словом vintage в названии и скажи, сколько из них осталось в количестве менее 5 штук».
«Сколько заказов я получил вчера? Сгруппируй по покупателю и общей выручке».
«Получи квитанцию 5550001 и скажи, какие транзакции были отправлены, а что еще предстоит отправить».
«Какова была статистика моего магазина за последние 30 дней? Сравни заказы, количество добавлений в избранное и активные товары».
«Для товара 1234567890 покажи мне все вариации, их SKU и текущее количество».

Claude считывает данные вашего магазина напрямую. Никакого копирования-вставки, никаких таблиц, никаких пользовательских конвейеров.

Инструменты (v0.1, только для чтения)

Инструмент	Что он делает
`etsy_search_listings`	Поиск по ключевым словам среди активных товаров, опционально в рамках магазина.
`etsy_get_listing`	Получение одного товара по ID.
`etsy_get_shop`	Получение записи магазина (название, валюта, количество, отпуск).
`etsy_search_orders`	Список квитанций (заказов) за период времени для одного магазина.
`etsy_get_order`	Получение одной квитанции по ID, включая транзакции по позициям.
`etsy_get_inventory`	Инвентарь на уровне вариаций (SKU, количество, цена) для товара.
`etsy_get_shop_stats`	Сводка за период: заказы, добавившие в избранное, выручка, товары.
`etsy_get_active_listings`	Пагинированный список всех активных товаров в магазине.

Эндпоинты для записи (создание черновика товара, обновление инвентаря, отметка квитанции как отправленной) намеренно отсутствуют в v0.1. Они запланированы на v0.2, как только стабилизируется эргономика инструментов только для чтения.

Установка

pip install etsy-mcp

v0.1 поставляется из этого репозитория. Публикация в PyPI ожидается — пока что устанавливайте через pip install git+https://github.com/alveyautomation/etsy-mcp или клонируйте и запустите pip install -e . локально.

Настройка учетных данных

Сервер считывает все из переменных окружения. Скопируйте .env.example в .env и заполните данные вашего арендатора:

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

Получение ключа API Etsy

Посетите https://www.etsy.com/developers/your-apps и зарегистрируйте приложение.
Скопируйте Keystring — это будет ETSY_API_KEY.
Настройте URI перенаправления для вашей однократной OAuth-авторизации (например, http://localhost:3000/callback).

Получение токена обновления (refresh token)

Etsy использует OAuth 2.0 с PKCE. Для начальной настройки выполните любой стандартный поток OAuth-PKCE один раз с этими параметрами:

response_type=code
client_id=<ваш keystring>
redirect_uri=<ваш зарегистрированный URI>
scope=listings_r shops_r transactions_r (только для чтения — минимум, необходимый этому серверу)
state=<случайное значение>
code_challenge=<PKCE> и code_challenge_method=S256

Обменяйте полученный код авторизации по адресу POST https://api.etsy.com/v3/public/oauth/token на токен доступа + токен обновления. Сохраните токен обновления как ETSY_REFRESH_TOKEN. Сервер будет использовать его для автоматического создания краткосрочных токенов доступа.

Используйте токены только для чтения с минимальными правами. v0.1 вызывает только эндпоинты GET, но эшелонированная защита означает, что вы никогда не должны предоставлять права на запись (*_w) токену обновления сервера. Когда выйдет v0.2 с инструментами для записи, вы сможете подключить их, создав новый токен с расширенными правами — но никогда не делайте наоборот.

Подключение к Claude Code

Добавьте в ~/.claude/claude_code_config.json (или в конфигурацию MCP вашего проекта):

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

Перезапустите Claude Code. Восемь инструментов etsy_* появятся в любой новой сессии.

Подключение к Claude Desktop

Отредактируйте ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) или %APPDATA%\Claude\claude_desktop_config.json (Windows) и добавьте тот же блок mcpServers, что и выше. Перезапустите настольное приложение.

Справочник инструментов

Каждый инструмент возвращает JSON-конверт:

{ "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)
)

Когда указан shop_id, запрос направляется к /shops/{shop_id}/listings/active. В противном случае он направляется к глобальному индексу /listings/active.

`etsy_get_listing`

etsy_get_listing(listing_id: int)

Возвращает запись товара или data: null при ошибке 404.

`etsy_get_shop`

etsy_get_shop(shop_id: int)

Запись магазина включает shop_name, currency_code, listing_active_count, num_favorers, is_vacation и многое другое.

`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 ограничивает размер страницы до 100; пагинация прозрачна. Ответ включает limit_reached: true, если limit был точкой усечения.

`etsy_get_order`

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

Возвращает полную квитанцию (с transactions[]) или data: null при ошибке 404.

`etsy_get_inventory`

etsy_get_inventory(listing_id: int)

Возвращает products[] с sku, property_values и offerings[] (количество, цена, доступность). Используйте количество предложения как каноническое число «доступно для продажи» для каждой вариации.

`etsy_get_shop_stats`

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

Сводка. Etsy не предоставляет первоклассный эндпоинт shop/stats в v3, поэтому этот инструмент синтезирует его из записи магазина (добавившие в избранное, количество активных товаров) и квитанций за период. Формат ответа:

{
  "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 принимает формат <N>d, максимум 365 дней.

`etsy_get_active_listings`

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

Пагинированный дамп всех активных товаров в магазине. Полезно для анализа всего каталога (например, «проверить мои заголовки на наличие отсутствующих ключевых слов»). Мягкое ограничение — 1000, чтобы вызов одного инструмента оставался в разумных пределах.

Локальная разработка

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 (gitleaks, trufflehog, ruff, форматировщик, очистка отпечатков арендатора):

pip install pre-commit
pre-commit install

Интеграционные тесты с реальной песочницей Etsy скрыты за флагом ETSY_INTEGRATION_TESTS=1. Они не требуются для обычного участия в разработке.

Устранение неполадок

Failed to refresh Etsy access token — ваш токен обновления истек или был отозван. Токены обновления Etsy действуют 90 дней с момента выпуска, но только при регулярном использовании. Запустите повторно OAuth-PKCE для создания нового токена.

Missing required environment variables — сервер попытался запуститься до того, как был загружен его файл .env. Либо экспортируйте переменные в родительской оболочке, либо убедитесь, что конфигурация вашего хоста MCP включает их в блоке env.

HTTP 403 при работе с квитанциями/транзакциями — у токена обновления отсутствуют права transactions_r. Повторно выполните авторизацию с правами на чтение, перечисленными выше.

Пустые результаты при наличии данных — подтвердите shop_id. Эндпоинты Etsy /shops/{shop_id}/... возвращают данные только для тех магазинов, для которых был авторизован токен OAuth.

Пагинация кажется медленной — Etsy ограничивает размер страницы до 100 за запрос, а не мы. Для больших периодов времени (длинная история заказов) ожидайте несколько циклов запросов. Уменьшите аргумент limit, чтобы ограничить вызов.

Участие в разработке

Приветствуются сообщения об ошибках и pull-запросы. Пожалуйста:

Запустите pytest перед открытием PR (pip install -e ".[dev]").
Запустите pre-commit run --all-files.
Ограничьте дополнения к v0.1 только чтением. Эндпоинты для записи появятся в v0.2.
Используйте только синтетические данные в тестах — никаких реальных названий магазинов, ID товаров или номеров квитанций.

Лицензия

MIT — см. LICENSE.

Отказ от ответственности

etsy-mcp является неофициальной сторонней интеграцией. Она не одобрена, не аффилирована и не поддерживается Etsy, Inc. «Etsy» является торговой маркой Etsy, Inc. Используйте на свой страх и риск; проверяйте поведение в своем магазине, прежде чем полагаться на него при принятии производственных решений.

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.

ParametersJSON Schema

Name	Required	Description	Default
`shop_id`	Yes
`limit`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Since no annotations are provided, the description carries full burden. It notes pagination behavior and a soft cap on limit, but does not clarify that the operation is read-only or mention any other behavioral traits, which is insufficient for a tool with no annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Very concise, using a clear docstring format with Args and Returns. Every sentence adds value; no wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 2 parameters and an output schema (not shown but present), the description adequately covers the tool's functionality. It explains return structure ('JSON envelope, data.listings'), which is sufficient with the output schema present.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description adds meaning beyond the schema. It defines shop_id as 'Etsy ShopID' (repetitive but confirms type) and explains limit as a 'soft cap' with default 200 and max 1000, providing valuable context not in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states 'List active listings for a shop, paginating transparently' which specifies the action (list), resource (active listings), and scope (for a shop, with automatic pagination). Distinguishes from siblings like etsy_get_listing (single) and etsy_search_listings (search across shops).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Implicitly describes usage for listing active listings of a shop, but provides no explicit guidance on when to use this tool versus alternatives, nor any conditions or exclusions among the 7 sibling tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema

Name	Required	Description	Default
`listing_id`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must disclose behavioral traits. It mentions the return structure (JSON envelope, products, offerings) and that data can be null, but does not specify whether the operation is read-only, authentication needs, or rate limits. Adequate but not thorough.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise, with a clear header sentence and structured Args/Returns sections. No redundancy or unnecessary information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (one parameter, output schema exists), the description covers purpose, parameter, and return value. It lacks usage guidelines, but for a straightforward fetch operation, it is largely complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The single parameter listing_id is described as 'Etsy ListingID', adding meaning beyond the schema title 'Listing Id'. The description explains its purpose clearly, compensating for the 0% schema description coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Fetch') and resource ('inventory record'), specifying it includes variations and offerings for a listing. It distinguishes from siblings like etsy_get_listing (listing details) and etsy_get_active_listings (list of listings).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains what the tool returns but does not explicitly state when to use it versus alternatives. No guidance on when not to use or prerequisites is provided, though the purpose is clear enough for an agent to infer usage context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema

Name	Required	Description	Default
`listing_id`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A3.8/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It states it 'fetches' (read-only) and returns null if not found, which is helpful. However, it does not disclose any potential side effects, permissions, rate limits, or other behavioral traits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise with no wasted words. It front-loads the purpose, then clearly lists args and returns. Every sentence serves a purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (one parameter, no annotations, output schema exists), the description adequately covers the essentials. It mentions what the tool does, the argument needed, and the return format including the null case. Could mention error handling beyond null, but not necessary for basic completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds meaning beyond the schema by specifying 'Etsy ListingID (integer)' for the listing_id parameter. This clarifies the parameter's type and scope, which is valuable given the schema only provides 'Listing Id' and type integer.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Fetch the full record for a single listing,' which is a specific verb+resource. It distinguishes from sibling tools like etsy_search_listings (which searches multiple) and etsy_get_active_listings (which gets multiple active listings).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description does not provide any guidance on when to use this tool versus alternatives. It lacks explicit when-to-use or when-not-to-use information, leaving the agent to infer from context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema

Name	Required	Description	Default
`receipt_id`	Yes
`shop_id`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

B3.4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries the burden. It discloses the behavior (fetch receipt with transactions), fallback for shop_id, and return format. However, it omits information on authentication or rate limits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Description is short and structured with Args and Returns sections. No unnecessary words, but the overall structure is clear and efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no annotations and an output schema (stated but not shown), description covers basics: purpose, parameters, return format. However, it lacks guidance on when to use this tool vs. search_orders, which is a gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so description must add meaning. It explains receipt_id is an integer and shop_id is an integer with a fallback to default. This adds value, but could provide more detail on source of IDs.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description states 'Fetch full receipt (order) detail including transactions' with a clear verb and resource. It specifies that it includes transactions, distinguishing it from sibling tools like etsy_get_listing and etsy_search_orders.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives like etsy_search_orders. The description only mentions fallback behavior for shop_id but does not provide context for tool selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema

Name	Required	Description	Default
`shop_id`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.1/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries burden. It discloses return format (JSON envelope with data field), example fields (name, currency_code, etc.), and null behavior on not found. Lacks error or auth info, but sufficient for a simple read operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences with args/returns section. Every sentence adds value: purpose, parameter, return details. No fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simple tool (one param, no nested objects, output schema exists), description covers purpose, parameter, return structure and field examples. Sufficient for an agent to understand usage and outcome.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Only one parameter (shop_id) with 0% schema description coverage. Description adds 'Etsy ShopID (integer)' context, clarifying it's the shop identifier. Compensates for missing schema documentation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states 'Fetch the shop record for a single shop,' which is a specific verb-resource pair. It clearly distinguishes from sibling tools like etsy_get_shop_stats (stats) or etsy_get_listing (listing entity).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus siblings. Does not mention alternatives or conditions like 'use this instead of etsy_get_shop_stats when only basic shop info is needed.'

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema

Name	Required	Description	Default
`shop_id`	Yes
`period`	No		30d

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A3.7/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description bears full burden for behavioral disclosure. It describes the return format but omits any mention of side effects, error conditions, authorization requirements, or rate limits, limiting transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise with a clear structure using Args and Returns sections; every sentence adds value without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given two parameters and an output schema, the description adequately explains both parameters and the return structure, but lacks details on error conditions or authentication requirements.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds substantial meaning beyond the input schema, explaining shop_id as 'Etsy ShopID' and period as a lookback window with format '<N>d' and maximum 365 days, compensating for 0% schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Return' and the resource 'aggregated stats (orders, favorers, active listings, revenue) for a shop over a given period', and it is distinct from sibling tools that handle listings, inventory, orders, or searches.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description does not provide explicit guidance on when to use this tool versus alternatives, nor does it mention exclusions or prerequisites, leaving the agent to infer usage solely from the purpose.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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}}.

ParametersJSON Schema

Name	Required	Description	Default
`query`	Yes
`shop_id`	No
`limit`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.1/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must carry the burden. It discloses the return format (JSON envelope with ok, data, results, count) and an enforced limit of 100, but lacks details on authentication, rate limits, or any read-only guarantee.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and well-structured with Args and Returns sections. Every sentence adds value with no redundancy or fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple 3-parameter search tool with an output schema, the description covers purpose, parameters, and return format adequately. It lacks explicit comparison to siblings, but is otherwise complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, but the description fully explains all three parameters: query as free-text, shop_id as optional scoping, and limit with a cap. This adds meaningful detail beyond the schema names.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Search active Etsy listings by keyword' with a specific verb and resource. It distinguishes from siblings like 'etsy_get_listings' by focusing on keyword search and optional shop_id scoping.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides context that omitting shop_id queries the global index, but does not explicitly compare to sibling tools like 'etsy_get_active_listings' or give when-not-to-use guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema

Name	Required	Description	Default
`date_from`	Yes
`date_to`	Yes
`shop_id`	No
`status`	No
`limit`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.2/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Without annotations, the description carries full burden. It discloses transparent pagination handling, limit cap (1000, with 100 per page), default shop_id fallback, and return format. It does not mention read-only nature or rate limits, but for a search tool the disclosed behaviors are substantial.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with a summary sentence followed by bullet-pointed parameter details. Every sentence adds value, no redundancy. It is concise yet comprehensive, fitting all necessary information into a compact format.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the output schema exists (not shown but indicated), the description adequately covers return structure ('JSON envelope with data.orders'). All parameters, default behaviors, and pagination are explained. No critical gaps remain for a search tool with moderate complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds extensive meaning beyond the input schema: date format (ISO), inclusive window semantics, shop_id fallback to ETSY_DEFAULT_SHOP_ID, status enum values, limit with transparent pagination. Schema coverage is 0%, so description fully compensates, making each parameter's purpose and constraints clear.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it searches receipts/orders by date window for a shop. 'Search receipts (orders) created in the inclusive [date_from, date_to] window for a shop.' is a specific verb+resource+scope. However, it does not differentiate from sibling tools like etsy_get_order or etsy_search_listings, leaving ambiguity about when to use this versus alternatives.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for searching orders within a date range, with optional filters. Yet it provides no explicit guidance on when not to use it or references to sibling tools for alternative use cases. The context of searching by shop and date window is clear but lacks exclusionary criteria.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

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

8 tool updatesv0.1.0Apr 27, 2026
- First observedetsy_get_active_listings
- First observedetsy_get_inventory
- First observedetsy_get_listing
- First observedetsy_get_order
- First observedetsy_get_shop
- First observedetsy_get_shop_stats
- First observedetsy_search_listings
- First observedetsy_search_orders

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.8/5.0

Scored 2026-04-27 05:15 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 issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

agentcentral AOAuth
to.agentcentral
Hosted Amazon Seller Central and Amazon Ads MCP server for Claude, ChatGPT, Cursor, and agents.
E-commerce & Retail Customer Support
26
DataDoe MCPOAuth
com.datadoe
Hosted Amazon Seller and Vendor MCP server for Claude, ChatGPT, Cursor, Codex, Gemini, Copilot.
E-commerce & Retail CRM
215
DuckHub QR Menu AOAuth
com.duck-hub
Hosted MCP server to manage a restaurant menu from AI agents - 39 tools over the DuckHub API.
E-commerce & Retail Content Management Systems
3
argo-mcp B
io.github.Argo-RPG-Platform
MCP server for Argo RPG Platform — connects AI assistants to campaign data via OAuth2
Games & Gamification Knowledge & Memory
6221

Related MCP Servers

etsy-mcp-server
E-commerce & Retail Customer Support
rodsanchez196-ops
F
license
Not graded
quality
D
maintenance
This is a deployable remote MCP server that lets OpenAI Agent Builder connect directly to Etsy using Etsy OAuth 2.0 with PKCE.
Updated 3 months ago (2026-06-19 06:32 UTC)
-
@mcpengine/etsy
E-commerce & Retail Payments & Billing
BusyBee3333
F
license
C
quality
D
maintenance
Comprehensive MCP server for the Etsy API v3, providing 50+ tools to manage listings, shops, orders, payments, and more through natural language.
Updated 6 months ago (2026-03-13 21:37 UTC)
100
3
-
etsy-mcp-server
E-commerce & Retail
DColl
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.
Updated 3 months ago (2026-07-01 06:24 UTC)
26
1
MIT
MCP Tool Agent
chigurupatiakhil5
F
license
Not graded
quality
B
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.
Updated 2 months ago (2026-07-24 00:48 UTC)
-