Etsy MCP Server for OpenAI Agent Builder

This is a deployable remote MCP server that lets OpenAI Agent Builder connect directly to Etsy using Etsy OAuth 2.0 with PKCE.

Tools

• etsy_get_my_shops
• etsy_get_shop
• etsy_get_listings
• etsy_create_listing
• etsy_update_listing
• etsy_get_orders
• etsy_get_messages
• etsy_reply_to_message

Important: Etsy's official OpenAPI v3 spec does not expose conversations/messages or reply endpoints. The two message tools are registered so Agent Builder can see the requested surface, but they return unsupported_by_etsy_open_api_v3 instead of faking unsupported Etsy calls.

Environment Variables

PUBLIC_BASE_URL=https://your-deployed-etsy-mcp.example.com
PORT=3000
DATA_PATH=etsy-mcp-store.json
ETSY_CLIENT_ID=your_etsy_keystring
ETSY_API_KEYSTRING=your_etsy_keystring
ETSY_SHARED_SECRET=your_etsy_shared_secret

ETSY_CLIENT_ID and ETSY_API_KEYSTRING are normally the same Etsy keystring.

Etsy Developer Portal Setup

1. Go to https://www.etsy.com/developers/your-apps.
2. Create or open your Etsy app.
3. Copy the app keystring into ETSY_CLIENT_ID and ETSY_API_KEYSTRING.
4. Copy the shared secret into ETSY_SHARED_SECRET.
5. Add this exact OAuth redirect URI:

https://your-deployed-etsy-mcp.example.com/oauth/etsy/callback

6. Replace the host with the real deployed host used in PUBLIC_BASE_URL.
7. The URI must be HTTPS and must match exactly. No trailing slash.

The server requests these Etsy scopes:

shops_r shops_w listings_r listings_w transactions_r transactions_w

Local Development

npm install
cp .env.example .env
npm run dev

For local Agent Builder testing, expose the server with an HTTPS tunnel and set:

PUBLIC_BASE_URL=https://your-tunnel-host

Then add this redirect URI to Etsy:

https://your-tunnel-host/oauth/etsy/callback

Deployment

Deploy to any Node host that supports persistent storage for the JSON token store, such as Render, Railway, Fly.io, or a VPS.

Build command:

npm install && npm run build

Start command:

npm start

Set all environment variables in the hosting provider.

If your platform has ephemeral disk, set DATA_PATH to a mounted persistent volume path or replace the JSON store with Postgres/Redis before production use.

OpenAI Agent Builder Setup

In Agent Builder, add a remote MCP connection:

Field	Value
MCP Server URL	https://your-deployed-etsy-mcp.example.com
Authentication	OAuth
Headers	None

Do not use:

https://your-deployed-etsy-mcp.example.com/mcp
https://your-deployed-etsy-mcp.example.com/sse

When Agent Builder connects, it discovers:

https://your-deployed-etsy-mcp.example.com/.well-known/oauth-protected-resource
https://your-deployed-etsy-mcp.example.com/.well-known/oauth-authorization-server

The OAuth flow then sends Employee #1 to Etsy, Employee #1 approves the Etsy app, and Agent Builder receives an MCP bearer token for subsequent tool calls.

Etsy API Routes Used

The server calls Etsy Open API v3:

GET   /v3/application/users/{user_id}/shops
GET   /v3/application/shops/{shop_id}
GET   /v3/application/shops/{shop_id}/listings
GET   /v3/application/shops/{shop_id}/listings/active
POST  /v3/application/shops/{shop_id}/listings
PATCH /v3/application/shops/{shop_id}/listings/{listing_id}
GET   /v3/application/shops/{shop_id}/receipts

Every Etsy API call sends:

Authorization: Bearer <etsy_oauth_access_token>
x-api-key: <keystring>:<shared_secret>