Etsy MCP Server

A local read-only MCP server for Etsy shops, active listings, and listing variation inventory.

Quick Install

Automated & IDE Setup

Copy the AI prompt to install this server into Claude Code, Cursor, or another agent — or use 1-click editor setup below.

One-click editor setup isn’t available for this listing yet — we don’t have a confirmed install command, and we’d rather show nothing than point your editor at the wrong package or host. Follow the project’s own setup instructions, linked above.

Manual Client & Custom JSON ConfigExpand JSON ▾

No confirmed setup config for this listing yet. We only publish a config block when the install details come from the project itself — its README, its docs, or a verified owner. We haven’t found those for etsy-mcp-server, and we’d rather show nothing than a guess you’d paste into your client. Follow the project’s own setup instructions for the current steps.

Documentation Overview

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

Terminal

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

bash

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

bash

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:

Terminal

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

Enter your keystring and shared secret in the hidden terminal prompts, authorize only shops_r and listings_r 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 <shop name or ID> 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 shops_r and listings_r, verify my shop, and offer the user-level Codex connection.”

🔧 Quick Start

Basic Setup

server.ts

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();



// Create API client

const client = new EtsyClient({

  keystring: 'your-api-key',

  sharedSecret: 'your-shared-secret', // REQUIRED for v3 API compliance

  accessToken: tokens.access_token,

  refreshToken: tokens.refresh_token,

  expiresAt: tokens.expires_at

});



// Make API calls

const user = await client.getUser();

console.log('User:', user);

Browser Usage

server.ts

<script type="module">

import { EtsyClient, AuthHelper } from 'https://unpkg.com/@profplum700/etsy-v3-api-client/dist/browser.esm.js';



// Your code here...

</script>

Or using UMD:

server.ts

<script src="https://unpkg.com/@profplum700/etsy-v3-api-client/dist/browser.umd.js"></script>

<script>

const { EtsyClient, AuthHelper } = EtsyApiClient;

// Your code here...

</script>

Node.js Usage

server.ts

// CommonJS

const { EtsyClient, AuthHelper } = require('@profplum700/etsy-v3-api-client');



// ES Modules

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

🔐 Authentication

OAuth 2.0 Flow

Create AuthHelper with your app credentials
Generate authorization URL for user to visit
Handle callback with authorization code
Exchange code for tokens
Use tokens with EtsyClient

server.ts

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



const authHelper = new AuthHelper({

  keystring: 'your-api-key',

  redirectUri: 'https://your-app.com/callback',

  scopes: [

    ETSY_SCOPES.SHOPS_READ,

    ETSY_SCOPES.LISTINGS_READ,

    ETSY_SCOPES.PROFILE_READ

  ]

});



// Step 1: Get authorization URL

const authUrl = await authHelper.getAuthUrl();

// Redirect user to authUrl



// Step 2: Handle callback (in your callback endpoint)

const { code, state } = getCallbackParams(); // Your implementation

const expectedState = await authHelper.getState();



if (state === expectedState) {

  await authHelper.setAuthorizationCode(code, state);

  const tokens = await authHelper.getAccessToken();

  // Store tokens securely

}

Available Scopes

server.ts

import { ETSY_SCOPES, COMMON_SCOPE_COMBINATIONS } from '@profplum700/etsy-v3-api-client';



// Individual scopes

const scopes = [

  ETSY_SCOPES.SHOPS_READ,

  ETSY_SCOPES.LISTINGS_WRITE,

  ETSY_SCOPES.TRANSACTIONS_READ

];



// Pre-defined combinations

const readOnlyScopes = COMMON_SCOPE_COMBINATIONS.SHOP_READ_ONLY;

const managementScopes = COMMON_SCOPE_COMBINATIONS.SHOP_MANAGEMENT;

🏪 Client Usage

Creating a Client

server.ts

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



const client = new EtsyClient({

  keystring: 'your-api-key',

  sharedSecret: 'your-shared-secret', // Get this from Your Apps page on Etsy

  accessToken: 'user-access-token',

  refreshToken: 'user-refresh-token',

  expiresAt: new Date('2024-12-31T23:59:59Z'),



  // Optional configuration

  rateLimiting: {

    enabled: true,

    maxRequestsPerSecond: 5,

    maxRequestsPerDay: 5000 // Conservative local fallback; Etsy response headers report this app's actual quota
  },

  caching: {

    enabled: true,

    ttl: 300 // 5 minutes

  }

});

Making API Calls

server.ts

// Get current user

const user = await client.getUser();



// Get user's shops

const shops = await client.getUserShops();



// Get shop listings

const listings = await client.getListingsByShop('shop-id');



// Get specific listing

const listing = await client.getListing('listing-id');



// Search listings

const searchResults = await client.findAllListingsActive({

  keywords: 'vintage',

  taxonomy_id: 123,

  limit: 25

});

Error Handling

server.ts

import { EtsyApiError, EtsyAuthError, EtsyRateLimitError } from '@profplum700/etsy-v3-api-client';



try {

  const user = await client.getUser();

} catch (error) {

  if (error instanceof EtsyAuthError) {

    // Handle authentication errors

    console.error('Auth error:', error.message, error.code);

  } else if (error instanceof EtsyRateLimitError) {

    // Handle rate limiting

    console.error('Rate limited. Retry after:', error.retryAfter);

  } else if (error instanceof EtsyApiError) {

    // Handle API errors

    console.error('API error:', error.statusCode, error.message);

  } else {

    // Handle other errors

    console.error('Unexpected error:', error);

  }

}

💾 Token Storage

Built-in Storage Options

The client provides several storage mechanisms:

server.ts

import { 

  createDefaultTokenStorage,

  LocalStorageTokenStorage,

  SessionStorageTokenStorage,

  FileTokenStorage,

  MemoryTokenStorage

} from '@profplum700/etsy-v3-api-client';



// Automatic storage selection based on environment

const storage = createDefaultTokenStorage();



// Browser localStorage

const localStorage = new LocalStorageTokenStorage('etsy-tokens');



// Browser sessionStorage  

const sessionStorage = new SessionStorageTokenStorage('etsy-tokens');



// Node.js file storage

const fileStorage = new FileTokenStorage('./tokens.json');



// In-memory storage (not persistent)

const memoryStorage = new MemoryTokenStorage();



// Use with client

const client = new EtsyClient(config, storage);

Custom Storage

server.ts

import { TokenStorage } from '@profplum700/etsy-v3-api-client';



class CustomTokenStorage implements TokenStorage {

  async save(tokens: EtsyTokens): Promise<void> {

    // Your save implementation

  }



  async load(): Promise<EtsyTokens | null> {

    // Your load implementation

  }



  async clear(): Promise<void> {

    // Your clear implementation

  }

}

🚦 Rate Limiting

The client includes built-in rate limiting to respect Etsy's API limits:

server.ts

const client = new EtsyClient({

  // ... other config

  rateLimiting: {

    enabled: true,

Read the full README →View source on GitHub →

Related MCP Servers

View all in Developer Tools View all alternatives

Reviews

No reviews yet — be the first to share how this listing worked for you.

Frequently Asked Questions about Etsy MCP Server

We don't have a confirmed install command for etsy-mcp-server yet, so we don't publish a generated one — a guessed package name would point at the wrong package or none at all. Follow the project's own README or setup instructions (https://github.com/profplum700/etsy-v3-api-client) for the current steps.

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:

Live Dynamic SVG Preview

Markdown (GitHub README)

[![AllMCPs](https://allmcps.com/api/badge/etsy-mcp-server?style=directory)](https://allmcps.com/mcp/etsy-mcp-server)

HTML Embed

<a href="https://allmcps.com/mcp/etsy-mcp-server"><img src="https://allmcps.com/api/badge/etsy-mcp-server?style=directory" alt="Etsy MCP Server on AllMCPs" /></a>

Technical Specs & Signals

CategoryDeveloper Tools

27Quality signal: Emerging · 27/100How this signal is calculated ▾

Server availabilityNot measured

Not scored for repo-hosted servers — we can't reach the running server, only its GitHub page. Hosted MCP endpoints are health-checked live.

Verified ownership8/20

Documentation & tools11/30

Adoption & activity1/15

Community engagement0/10

A guidance signal from public completeness & health data — not a user rating. New listings start lower and rise as they add docs, get verified, and grow adoption. Signals we can't observe for a listing are skipped, not counted against it.

★ Featured

AllMCPs Server

The official MCP server for AllMCPs.com - submit and manage tools directly from your AI. The open directory for MCP servers. Connect Claude, Cursor, Windsurf, and AI agents to databases, tools, files, and APIs. Explore 10,000+ servers. AllMCPs is the premier, open directory for discovering, evaluating, and installing Model Context Protocol (MCP) servers to equip AI agents and LLMs with real-world superpowers.

Explore Server →

Own this project?

This directory is pre-filled from public sources. Claim via GitHub README, site badge, or DNS TXT to unlock edit access and the Official badge and attach your website — proof is checked automatically, then reviewed by our team.

Free dofollow backlink: add your website and place the AllMCPs badge on it — no claim needed. We detect it automatically and keep it verified as long as the badge stays live.

Claim & get free dofollow

Share & Embed

Add our SVG badge (dark/light directory styles) or embeddable widget to your site.

Explore more

More in 💻 Developer Tools →Best MCP servers for Developers →Alternatives to Etsy MCP Server →Install in Claude Desktop Install in Cursor Install in VS Code Setup guides for all 13 MCP clients

Etsy MCP Server

A local read-only MCP server for Etsy shops, active listings, and listing variation inventory.

Quick Install

Automated & IDE Setup

Copy the AI prompt to install this server into Claude Code, Cursor, or another agent — or use 1-click editor setup below.

Manual Client & Custom JSON ConfigExpand JSON ▾

Documentation Overview

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.

🚀 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

Terminal

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

bash

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

bash

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

🤖 Connect an agent to your Etsy shop

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

Terminal

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

🔧 Quick Start

Basic Setup

server.ts

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();



// Create API client

const client = new EtsyClient({

  keystring: 'your-api-key',

  sharedSecret: 'your-shared-secret', // REQUIRED for v3 API compliance

  accessToken: tokens.access_token,

  refreshToken: tokens.refresh_token,

  expiresAt: tokens.expires_at

});



// Make API calls

const user = await client.getUser();

console.log('User:', user);

Browser Usage

server.ts

<script type="module">

import { EtsyClient, AuthHelper } from 'https://unpkg.com/@profplum700/etsy-v3-api-client/dist/browser.esm.js';



// Your code here...

</script>

Or using UMD:

server.ts

<script src="https://unpkg.com/@profplum700/etsy-v3-api-client/dist/browser.umd.js"></script>

<script>

const { EtsyClient, AuthHelper } = EtsyApiClient;

// Your code here...

</script>

Node.js Usage

server.ts

// CommonJS

const { EtsyClient, AuthHelper } = require('@profplum700/etsy-v3-api-client');



// ES Modules

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

🔐 Authentication

OAuth 2.0 Flow

Create AuthHelper with your app credentials
Generate authorization URL for user to visit
Handle callback with authorization code
Exchange code for tokens
Use tokens with EtsyClient

server.ts

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



const authHelper = new AuthHelper({

  keystring: 'your-api-key',

  redirectUri: 'https://your-app.com/callback',

  scopes: [

    ETSY_SCOPES.SHOPS_READ,

    ETSY_SCOPES.LISTINGS_READ,

    ETSY_SCOPES.PROFILE_READ

  ]

});



// Step 1: Get authorization URL

const authUrl = await authHelper.getAuthUrl();

// Redirect user to authUrl



// Step 2: Handle callback (in your callback endpoint)

const { code, state } = getCallbackParams(); // Your implementation

const expectedState = await authHelper.getState();



if (state === expectedState) {

  await authHelper.setAuthorizationCode(code, state);

  const tokens = await authHelper.getAccessToken();

  // Store tokens securely

}

Available Scopes

server.ts

import { ETSY_SCOPES, COMMON_SCOPE_COMBINATIONS } from '@profplum700/etsy-v3-api-client';



// Individual scopes

const scopes = [

  ETSY_SCOPES.SHOPS_READ,

  ETSY_SCOPES.LISTINGS_WRITE,

  ETSY_SCOPES.TRANSACTIONS_READ

];



// Pre-defined combinations

const readOnlyScopes = COMMON_SCOPE_COMBINATIONS.SHOP_READ_ONLY;

const managementScopes = COMMON_SCOPE_COMBINATIONS.SHOP_MANAGEMENT;

🏪 Client Usage

Creating a Client

server.ts

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



const client = new EtsyClient({

  keystring: 'your-api-key',

  sharedSecret: 'your-shared-secret', // Get this from Your Apps page on Etsy

  accessToken: 'user-access-token',

  refreshToken: 'user-refresh-token',

  expiresAt: new Date('2024-12-31T23:59:59Z'),



  // Optional configuration

  rateLimiting: {

    enabled: true,

    maxRequestsPerSecond: 5,

    maxRequestsPerDay: 5000 // Conservative local fallback; Etsy response headers report this app's actual quota
  },

  caching: {

    enabled: true,

    ttl: 300 // 5 minutes

  }

});

Making API Calls

server.ts

// Get current user

const user = await client.getUser();



// Get user's shops

const shops = await client.getUserShops();



// Get shop listings

const listings = await client.getListingsByShop('shop-id');



// Get specific listing

const listing = await client.getListing('listing-id');



// Search listings

const searchResults = await client.findAllListingsActive({

  keywords: 'vintage',

  taxonomy_id: 123,

  limit: 25

});

Error Handling

server.ts

import { EtsyApiError, EtsyAuthError, EtsyRateLimitError } from '@profplum700/etsy-v3-api-client';



try {

  const user = await client.getUser();

} catch (error) {

  if (error instanceof EtsyAuthError) {

    // Handle authentication errors

    console.error('Auth error:', error.message, error.code);

  } else if (error instanceof EtsyRateLimitError) {

    // Handle rate limiting

    console.error('Rate limited. Retry after:', error.retryAfter);

  } else if (error instanceof EtsyApiError) {

    // Handle API errors

    console.error('API error:', error.statusCode, error.message);

  } else {

    // Handle other errors

    console.error('Unexpected error:', error);

  }

}

💾 Token Storage

Built-in Storage Options

The client provides several storage mechanisms:

server.ts

import { 

  createDefaultTokenStorage,

  LocalStorageTokenStorage,

  SessionStorageTokenStorage,

  FileTokenStorage,

  MemoryTokenStorage

} from '@profplum700/etsy-v3-api-client';



// Automatic storage selection based on environment

const storage = createDefaultTokenStorage();



// Browser localStorage

const localStorage = new LocalStorageTokenStorage('etsy-tokens');



// Browser sessionStorage  

const sessionStorage = new SessionStorageTokenStorage('etsy-tokens');



// Node.js file storage

const fileStorage = new FileTokenStorage('./tokens.json');



// In-memory storage (not persistent)

const memoryStorage = new MemoryTokenStorage();



// Use with client

const client = new EtsyClient(config, storage);

Custom Storage

server.ts

import { TokenStorage } from '@profplum700/etsy-v3-api-client';



class CustomTokenStorage implements TokenStorage {

  async save(tokens: EtsyTokens): Promise<void> {

    // Your save implementation

  }



  async load(): Promise<EtsyTokens | null> {

    // Your load implementation

  }



  async clear(): Promise<void> {

    // Your clear implementation

  }

}

🚦 Rate Limiting

The client includes built-in rate limiting to respect Etsy's API limits:

server.ts

const client = new EtsyClient({

  // ... other config

  rateLimiting: {

    enabled: true,

Read the full README →View source on GitHub →

Related MCP Servers

View all in Developer Tools View all alternatives

Reviews

No reviews yet — be the first to share how this listing worked for you.

Frequently Asked Questions about Etsy MCP Server

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:

Live Dynamic SVG Preview

Markdown (GitHub README)

[![AllMCPs](https://allmcps.com/api/badge/etsy-mcp-server?style=directory)](https://allmcps.com/mcp/etsy-mcp-server)

HTML Embed

<a href="https://allmcps.com/mcp/etsy-mcp-server"><img src="https://allmcps.com/api/badge/etsy-mcp-server?style=directory" alt="Etsy MCP Server on AllMCPs" /></a>

Technical Specs & Signals

CategoryDeveloper Tools

27Quality signal: Emerging · 27/100How this signal is calculated ▾

Server availabilityNot measured

Not scored for repo-hosted servers — we can't reach the running server, only its GitHub page. Hosted MCP endpoints are health-checked live.

Verified ownership8/20

Documentation & tools11/30

Adoption & activity1/15

Community engagement0/10

★ Featured

AllMCPs Server

Explore Server →

Own this project?

Free dofollow backlink: add your website and place the AllMCPs badge on it — no claim needed. We detect it automatically and keep it verified as long as the badge stays live.

Claim & get free dofollow

Share & Embed

Add our SVG badge (dark/light directory styles) or embeddable widget to your site.