etsy-mcp-server

# Etsy MCP Server This project exposes a subset of the [Etsy API](https://developers.etsy.com/) 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](https://github.com/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: ```bash 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: ```bash npm install ``` Then, build the server: ```bash 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: ```bash 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 ```bash 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:** ```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:** ```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:** ```bash docker run --rm \ -v ./etsy_mcp_settings.json:/usr/src/app/etsy_mcp_settings.json \ etsy-mcp-server ``` **PowerShell:** ```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: ```json { "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: ```bash cp .env.example .env # Edit .env with your Etsy API credentials ``` 2. Start with Docker Compose: ```bash docker-compose --profile production up ``` ### Production Deployment **Multi-platform Builds** (for ARM64/Apple Silicon): ```bash # 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**: ```bash # 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:** ```bash # 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**: ```bash 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 ```bash npm run build npm run inspector ``` 2. **For Deployment**: Use Docker with MCP clients ```bash 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.