Etsy MCP server

Etsy API v3 Client

A modern, universal TypeScript/JavaScript client for the Etsy Open API v3 with full OAuth 2.0 PKCE authentication support. Works seamlessly in both browser and Node.js environments.

This repository is heavily based on the official Etsy OpenAPI specification (https://www.etsy.com/openapi/generated/oas/3.0.0.json), as referenced in Etsy's API documentation (https://developers.etsy.com/documentation/reference).

🚀 Features

• Universal Compatibility: Works in browsers, Node.js, and Web Workers
• OAuth 2.0 PKCE Authentication: Full support for secure authentication flow
• TypeScript First: Complete type definitions with IntelliSense support
• Rate Limiting: Built-in request throttling to respect API limits
• Token Management: Automatic token refresh with configurable storage
• Caching: Optional response caching to improve performance
• Error Handling: Comprehensive error types for different failure scenarios
• Zero Dependencies: No external runtime dependencies

📦 Installation

npm install @profplum700/etsy-v3-api-client

yarn add @profplum700/etsy-v3-api-client

pnpm add @profplum700/etsy-v3-api-client

🤖 Connect an agent to your Etsy shop

The companion @profplum700/etsy-mcp-server package runs locally over stdio and exposes read-only shop, active-listing, and listing-inventory tools. It requires Node.js 24+, your own approved Etsy developer app, and an OS credential store. It does not use a hosted endpoint.

Register http://localhost:3030/oauth/redirect as the Etsy app callback if required, then run this in a local interactive terminal:

npx --yes @profplum700/etsy-mcp-server@latest setup

Enter your keystring and shared secret in the hidden terminal prompts, authorize only shopsr and listingsr in Etsy, then choose whether to add the server to your user-level Codex MCP configuration. For another stdio client, configure npx --yes @profplum700/etsy-mcp-server@latest serve as its launch command.

You can connect multiple shops without replacing earlier profiles. Run setup --reuse-app --manual-browser to reuse the saved developer app credentials, then open the printed authorization URL in the browser profile signed in to the shop you want to add. Use status to see saved shops and use to choose which one MCP tools query. disconnect removes only the active shop; disconnect --all removes every saved profile. Use remove-codex to remove the Codex entry without disconnecting any shop.

Prompt for an agent: “Set up the local Etsy MCP server. Do not ask me to paste Etsy credentials into chat or save them in a repository or environment file. Run the setup command in an interactive local terminal so I can enter them there; request only shopsr and listingsr, verify my shop, and offer the user-level Codex connection.”

🔧 Quick Start

Basic Setup

import { EtsyClient, AuthHelper } from '@profplum700/etsy-v3-api-client';

// Create authentication helper
const authHelper = new AuthHelper({
  keystring: 'your-api-key',
  redirectUri: 'https://your-app.com/callback',
  scopes: ['shops_r', 'listings_r']
});

// Get authorization URL
const authUrl = await authHelper.getAuthUrl();
console.log('Visit this URL to authorize:', authUrl);

// After user authorization, exchange code for tokens
const state = await authHelper.getState();
await authHelper.setAuthorizationCode('authorization-code-from-callback', state);
const tokens = await authHelper.getAccessToken();

Shortened. The full README is on GitHub.