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:

**

... View full README on GitHub