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.

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.

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

Option 1: Build Locally

docker build -t etsy-mcp-server .

Option 2: Pull from Registry (when available)

# Future: docker pull etsy-mcp-server:latest

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

getShop

Fetch information about a shop. Required argument: shop_id.

getMe

Return basic info about the authenticated user, including user_id and shop_id. This endpoint takes no arguments.

getListingsByShop

List the listings in a shop. Supports an optional state parameter (e.g. active, draft). Requires shop_id.

createDraftListing

Create a new physical draft listing using POST /v3/application/shops/{shop_id}/listings. The tool accepts all fields supported by Etsy's createDraftListing endpoint.

uploadListingImage

Upload an image to a listing. Requires shop_id, listing_id and image_path. (Implementation is currently a placeholder.)

updateListing

Update an existing listing. Requires shop_id and listing_id. Optional fields include title, description and price.

getShopReceipts

Retrieve receipts for a shop. Requires shop_id.

getShopSections

Retrieve the list of sections in a shop. Requires shop_id.

getShopSection

Retrieve a single shop section by shop_id and shop_section_id.

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.