Etsy MCP Server

This project exposes a subset of the Etsy API through the Model Context Protocol. It allows tools to be called from an MCP client to retrieve shop data and manage listings.

Based on profplum700/etsy-mcp-server (MIT). This version tracks Etsy API changes the original predates:

• x-api-key header now requires the keystring:sharedSecret format (Etsy change, 2026-02)
• readiness_state_id (processing profile) is required for physical listings (Etsy change, 2025-06), with tools to list and create processing profiles
• createDraftListing/updateListing accept tags, materials, shipping_profile_id, return_policy_id, shop_section_id and type, with correct comma-separated encoding for array fields
• new tools: getShopShippingProfiles, getShopReturnPolicies, getShopReadinessStateDefinitions, createShopReadinessStateDefinition

OAuth Setup

The server requires a valid Etsy API keystring, shared secret, and OAuth refresh token. You can provide these credentials in two ways:

1. Environment Variables: Set ETSY_API_KEY, ETSY_SHARED_SECRET, and ETSY_REFRESH_TOKEN.
2. Settings File: Create an etsy_mcp_settings.json file by copying etsy_mcp_settings.example.json and filling in your credentials. By default the file is looked up in the project root; set ETSY_SETTINGS_PATH to use a different location.

If you do not yet have a refresh token, run the following helper script:

npx tsx src/get-refresh-token --keystring YOUR_KEY --shared-secret YOUR_SECRET

The script opens a browser window for authentication and prints the refresh token to the console.

Local Development

These instructions are for running the server directly on your machine for development purposes.

First, install dependencies:

npm install

Then, build the server:

npm run build

You can also use npm run watch to automatically rebuild the server when you make code changes.

Configuration File Location

For local development, place your etsy_mcp_settings.json file in the project root directory (same level as package.json). The server will automatically detect and load it.

Running the Server

After building, start the server with:

npm start

Important: This MCP server communicates over stdio and is designed to be connected to by MCP clients (like Claude Desktop, Cline, or other MCP-compatible applications). When run directly, it will start and wait for MCP protocol messages. To test functionality, use the MCP Inspector (see Debugging section) or connect it to an MCP client.

MCP Client Integration

To use this server with an MCP client, you typically need to:

1. Claude Desktop: Add the server configuration to your Claude Desktop settings
2. Cline: Configure the server in your MCP server settings
3. Other MCP Clients: Refer to your client's documentation for adding MCP servers

The server will be started automatically by the MCP client when needed.

Running with Docker

This is the recommended method for deployment or for running the server in a standardized environment.

Quick Start with Docker

docker build -t etsy-mcp-server .

Configuration File Location for Docker

For Docker usage, your etsy_mcp_settings.json file should be located in the same directory where you run the docker run command. The ./ in the volume mount refers to your current working directory.

Container Behavior

Important: MCP servers are not long-running background services. When you start the container, it will:

1. Load your Etsy credentials (from environment variables or settings file)
2. Print "Etsy MCP server running on stdio"
3. Wait for MCP protocol messages on stdin
4. Exit after a short time if no MCP client connects

This is normal behavior. The container is designed to be started by MCP clients when needed, not to run continuously like a web server.

Starting the Container

You can supply your Etsy credentials either as environment variables or by mounting your settings file.

Option 1: Using Environment Variables

Bash:

docker run --rm \
  -e ETSY_API_KEY=YOUR_KEY \
  -e ETSY_SHARED_SECRET=YOUR_SECRET \
  -e ETSY_REFRESH_TOKEN=YOUR_TOKEN \
  etsy-mcp-server

PowerShell:

docker run --rm `
  -e ETSY_API_KEY=YOUR_KEY `
  -e ETSY_SHARED_SECRET=YOUR_SECRET `
  -e ETSY_REFRESH_TOKEN=YOUR_TOKEN `
  etsy-mcp-server

Option 2: Using a Settings File

Create an etsy_mcp_settings.json file in your current directory. Then, mount it into the container using the -v flag:

Bash:

docker run --rm \
  -v ./etsy_mcp_settings.json:/usr/src/app/etsy_mcp_settings.json \
  etsy-mcp-server

PowerShell:

docker run --rm `
  -v ./etsy_mcp_settings.json:/usr/src/app/etsy_mcp_settings.json `
  etsy-mcp-server

MCP Client Integration with Docker

To use this Docker container with MCP clients:

1. Claude Desktop: Configure the server to use the Docker command in your Claude Desktop settings
2. Cline: Set up the Docker command as your MCP server startup command
3. Other MCP Clients: Use the appropriate Docker command as the server executable

Example MCP client configuration:

{
  "command": "docker",
  "args": [
    "run",
    "--rm",
    "-v",
    "./etsy_mcp_settings.json:/usr/src/app/etsy_mcp_settings.json",
    "etsy-mcp-server"
  ]
}

The MCP client will automatically start the container when it needs to use the Etsy tools and stop it when done.

Docker Compose (Recommended)

For easier management, use Docker Compose:

1. Copy .env.example to .env and fill in your credentials:

   cp .env.example .env
   # Edit .env with your Etsy API credentials
   

2. Start with Docker Compose:

   docker-compose --profile production up
   

Production Deployment

Multi-platform Builds (for ARM64/Apple Silicon):

# Build for multiple architectures
docker buildx build --platform linux/amd64,linux/arm64 -t etsy-mcp-server:latest .

# Or build specifically for ARM64 (Apple Silicon)
docker buildx build --platform linux/arm64 -t etsy-mcp-server:arm64 .

Registry Deployment:

# Tag for registry
docker tag etsy-mcp-server:latest your-registry.com/etsy-mcp-server:1.0.0

# Push to registry
docker push your-registry.com/etsy-mcp-server:1.0.0

Docker Troubleshooting

Common Issues:

1. Container exits immediately: This is normal behavior for MCP servers when no client connects
2. Permission denied: Ensure Docker has proper file system access
3. Settings file not found: Check volume mount path matches your file location
4. Environment variables not loaded: Verify .env file syntax and variable names

Debug Commands:

# Check container logs
docker logs etsy-mcp-server

# Run container interactively for debugging
docker run -it --rm etsy-mcp-server sh

# Test container with manual input
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | docker run -i --rm etsy-mcp-server

Available tools

Shop

Tool	Description
getMe	Info about the authenticated user, including user_id and shop_id. No arguments.
getShop	Fetch information about a shop. Requires shop_id.
getShopSections	List the sections of a shop. Requires shop_id.
getShopShippingProfiles	List shipping profiles. Use the returned shipping_profile_id when creating a physical listing.
getShopReturnPolicies	List return policies. return_policy_id is required for physical listings in some regions (e.g. EU).
getShopReadinessStateDefinitions	List processing profiles. readiness_state_id is required for physical listings since 2025-06.
createShopReadinessStateDefinition	Create a processing profile (ready_to_ship or made_to_order with min/max processing time).

Listings

Tool	Description
getListingsByShop	List a shop's listings, with an optional state filter (active, draft, ...).
createDraftListing	Create a draft listing. Required: shop_id, title, description, price, quantity, who_made, when_made, taxonomy_id. Physical listings also need shipping_profile_id and readiness_state_id. Optional: tags, materials, return_policy_id, shop_section_id, type.
updateListing	Update a listing: title, description, price, tags, materials, shipping_profile_id, shop_section_id.
uploadListingImage	Upload an image file to a listing. Requires shop_id, listing_id and a local image_path.
getListingImages	List the images of a listing.
getListingFiles	List the files of a digital listing.
getListingInventory	Get inventory details for a listing.
updateListingInventory	Replace the inventory (products array) of a listing.

Seller taxonomy

Tool	Description
getSellerTaxonomyNodes	Retrieve the full hierarchy of seller taxonomy nodes.
getPropertiesByTaxonomyId	List product properties supported for a specific taxonomy node. Requires taxonomy_id.

Debugging

Using the MCP Inspector

For debugging and testing the server functionality, use the MCP Inspector with the local development setup:

npm run inspector

The inspector will:

1. Start a proxy server and web interface
2. Launch the locally built MCP server
3. Provide a URL to view communication logs and test tools interactively

Important: The MCP Inspector only works with the local development setup, not with Docker. This is because:

• Docker containers start and exit quickly when no MCP client connects
• The inspector needs direct access to the server process
• Network isolation prevents the inspector from communicating with containerized servers

Recommended Debugging Workflow

1. For Development and Testing: Use local development with the MCP Inspector

   npm run build
   npm run inspector
   

2. For Deployment: Use Docker with MCP clients

   docker build -t etsy-mcp-server .
   # Then use with your MCP client
   

This approach gives you the best of both worlds: interactive debugging locally and reliable deployment with Docker.