Skip to main content
Glama
deenesjakoruzh
alveyautomation

etsy-mcp

by alveyautomation
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

etsy-mcp

Etsy를 위한 최초의 프로덕션급 Model Context Protocol 서버입니다. 5분 안에 Claude를 Etsy 상점의 리스팅, 재고, 주문 및 통계와 연결하여 읽기 전용으로 사용할 수 있습니다.

License: MIT Python 3.10+ MCP

이 프로젝트의 목적

Etsy의 Open API v3는 문서화가 잘 되어 있고 안정적이지만, 자신의 상점에 LLM을 도입하려는 모든 판매자는 매번 OAuth와 페이지네이션 구현을 처음부터 다시 작성해야 합니다. 기존의 MCP 통합은 토큰 갱신, 재시도 로직, Etsy가 실제로 요구하는 상점별 페이지네이션 등이 빠진 단순한 데모 수준에 그칩니다.

Etsy 판매자로서 Claude(또는 MCP를 지원하는 AI 어시스턴트)가 내 상점에 무엇이 있는지(어떤 상품이 등록되어 있고, 어제 무엇이 배송되었으며, 재고가 부족한 상품은 무엇인지)를 바로 알기를 원한다면, 이 간극이 바로 "오늘의 주문 요약"이 즉시 작동하느냐 아니면 별도의 커스텀 통합이 필요하느냐의 차이를 만듭니다.

etsy-mcp는 그 간극을 메워줍니다. 이 서버는 8개의 읽기 전용 Etsy 엔드포인트를 모든 MCP 클라이언트에 노출하는 작고 잘 테스트된 MIT 라이선스 MCP 서버입니다. 수년간 대규모 이커머스 자동화를 운영해 온 경험을 바탕으로 구축되었습니다.

Related MCP server: @mcpengine/etsy

활용 방법

이 서버를 Claude Code, Claude Desktop 또는 모든 MCP 호스트에 연결한 후 다음과 같이 질문해 보세요:

  • "내 상점에서 제목에 vintage라는 단어가 포함된 리스팅을 검색하고, 수량이 5개 미만인 상품이 몇 개인지 알려줘."

  • "어제 주문을 몇 건 받았어? 구매자별로 그룹화하고 총 매출을 계산해 줘."

  • "영수증 5550001을 가져와서 어떤 거래가 배송되었고, 무엇이 아직 배송되지 않았는지 알려줘."

  • "지난 30일 동안의 상점 통계는 어땠어? 주문, 즐겨찾기 수, 활성 리스팅을 비교해 줘."

  • "리스팅 1234567890에 대해 모든 옵션(variation), 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

Etsy API 키 발급

  1. https://www.etsy.com/developers/your-apps에 방문하여 앱을 등록합니다.

  2. Keystring을 복사하여 ETSY_API_KEY로 설정합니다.

  3. 일회성 OAuth 부트스트랩을 위한 리다이렉트 URI(예: http://localhost:3000/callback)를 구성합니다.

리프레시 토큰 발급

Etsy는 PKCE를 사용하는 OAuth 2.0을 사용합니다. 부트스트랩을 위해 다음 파라미터로 표준 OAuth-PKCE 흐름을 한 번 실행하세요:

  • response_type=code

  • client_id=<your keystring>

  • redirect_uri=<your registered URI>

  • scope=listings_r shops_r transactions_r (읽기 전용 — 이 서버에 필요한 최소 권한)

  • state=<random>

  • 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를 재시작하면 8개의 etsy_* 도구가 새로운 세션에 나타납니다.

Claude Desktop에 연결

~/Library/Application Support/Claude/claude_desktop_config.json(macOS) 또는 %APPDATA%\Claude\claude_desktop_config.json(Windows)을 편집하고 위와 동일한 mcpServers 블록을 추가하세요. 데스크톱 앱을 재시작하세요.

도구 참조

모든 도구는 JSON 봉투(envelope)를 반환합니다:

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

리스팅 레코드를 반환하며, 404 발생 시 data: null을 반환합니다.

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이 잘림 지점일 경우 응답에 limit_reached: true가 포함됩니다.

etsy_get_order

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

전체 영수증(transactions[] 포함)을 반환하며, 404 발생 시 data: null을 반환합니다.

etsy_get_inventory

etsy_get_inventory(listing_id: int)

sku, property_values, offerings[](수량, 가격, 활성화 여부)가 포함된 products[]를 반환합니다. 옵션별로 "판매 가능한 수량"을 확인하려면 offering 수량을 사용하세요.

etsy_get_shop_stats

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

구성된 요약 데이터입니다. Etsy v3에는 공식적인 shop/stats 엔드포인트가 없으므로, 상점 레코드(즐겨찾기, 활성 리스팅 수)와 기간 내 영수증을 조합하여 생성합니다. 반환 형태:

{
  "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, formatter, tenant-fingerprint scrubber):

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가 로드되기 전에 서버가 시작되었습니다. 부모 셸에서 변수를 export하거나, MCP 호스트 설정의 env 블록에 포함되어 있는지 확인하세요.

HTTP 403 on receipts/transactions — 리프레시 토큰의 스코프에 transactions_r이 누락되었습니다. 위에서 언급한 읽기 스코프를 사용하여 다시 부트스트랩하세요.

데이터가 있는데 결과가 비어 있음 — shop_id를 확인하세요. Etsy의 /shops/{shop_id}/... 엔드포인트는 OAuth 토큰이 승인된 상점에 대해서만 데이터를 반환합니다.

페이지네이션이 느림 — Etsy가 요청당 페이지 크기를 100으로 제한하고 있습니다. 긴 기간(오랜 주문 기록)의 경우 여러 번의 왕복 통신이 발생합니다. limit 인수를 낮추어 호출 범위를 제한하세요.

기여

이슈와 풀 리퀘스트를 환영합니다. 다음 사항을 지켜주세요:

  • PR을 열기 전에 pytest를 실행하세요 (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
NameRequiredDescriptionDefault
shop_idYes
limitNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

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
NameRequiredDescriptionDefault
listing_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

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
NameRequiredDescriptionDefault
listing_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

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
NameRequiredDescriptionDefault
receipt_idYes
shop_idNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

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
NameRequiredDescriptionDefault
shop_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

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
NameRequiredDescriptionDefault
shop_idYes
periodNo30d

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

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
NameRequiredDescriptionDefault
queryYes
shop_idNo
limitNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

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
NameRequiredDescriptionDefault
date_fromYes
date_toYes
shop_idNo
statusNo
limitNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

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.

  1. 8 tool updatesv0.1.0
    • 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 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

Related MCP Connectors

Related MCP Servers

  • etsy-mcp-server

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