A TypeScript-based MCP server for interacting with the Etsy API, featuring a simple notes system.
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.
The server requires a valid Etsy API keystring, shared secret, and OAuth refresh token. You can provide these credentials in two ways:
ETSY_API_KEY
, ETSY_SHARED_SECRET
, and ETSY_REFRESH_TOKEN
.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.
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.
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.
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.
To use this server with an MCP client, you typically need to:
The server will be started automatically by the MCP client when needed.
This is the recommended method for deployment or for running the server in a standardized environment.
Option 1: Build Locally
docker build -t etsy-mcp-server .
Option 2: Pull from Registry (when available)
# Future: docker pull etsy-mcp-server:latest
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.
Important: MCP servers are not long-running background services. When you start the container, it will:
This is normal behavior. The container is designed to be started by MCP clients when needed, not to run continuously like a web server.
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
To use this Docker container with MCP clients:
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.
For easier management, use Docker Compose:
Copy .env.example
to .env
and fill in your credentials:
cp .env.example .env
# Edit .env with your Etsy API credentials
Start with Docker Compose:
docker-compose --profile production up
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
Common Issues:
.env
file syntax and variable namesDebug 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
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
.
For debugging and testing the server functionality, use the MCP Inspector with the local development setup:
npm run inspector
The inspector will:
Important: The MCP Inspector only works with the local development setup, not with Docker. This is because:
For Development and Testing: Use local development with the MCP Inspector
npm run build
npm run inspector
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.
An MCP server enabling AI agents to pay for services using HTTP 402 requests and MCP tools.
Provides Chinese Tung Shing (almanac) data, including calendar conversions, auspicious activities, and traditional metaphysical elements.
An MCP server that allows client agents to play the game of Minesweeper.
PiAPI MCP server makes user able to generate media content with Midjourney/Flux/Kling/Hunyuan/Udio/Trellis directly from Claude or any other MCP-compatible apps.
Perform bulk BNB and BEP20 token transfers on the BNB Smart Chain (BSC).
Provides AI assistants with comprehensive access to a Plex Media Server.
An intelligent trading assistant that fetches live stock prices using the Yahoo Finance API.
Generates O'RLY? (O'Reilly parody) book covers.
Generates true random coin flips using the random.org API.
A healthcare-focused RAG server using Groq API and Chroma for information retrieval from patient records.