Etsy

Um servidor MCP baseado em TypeScript para interagir com a API do Etsy, com um sistema simples de notas.

GitHub
9

Documentação

Etsy MCP Server

Este projeto expõe um subconjunto da API do Etsy através do Model Context Protocol. Ele permite que ferramentas sejam chamadas a partir de um cliente MCP para recuperar dados da loja e gerenciar anúncios.

Configuração OAuth

O servidor requer uma keystring válida da API do Etsy, um segredo compartilhado e um token de atualização OAuth. Você pode fornecer essas credenciais de duas maneiras:

  1. Variáveis de Ambiente: Defina ETSY_API_KEY, ETSY_SHARED_SECRET e ETSY_REFRESH_TOKEN.
  2. Arquivo de Configurações: Crie um arquivo etsy_mcp_settings.json copiando etsy_mcp_settings.example.json e preenchendo suas credenciais.

Se você ainda não tem um token de atualização, execute o seguinte script auxiliar:

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

O script abre uma janela do navegador para autenticação e imprime o token de atualização no console.

Desenvolvimento Local

Estas instruções são para executar o servidor diretamente na sua máquina para fins de desenvolvimento.

Primeiro, instale as dependências:

npm install

Em seguida, compile o servidor:

npm run build

Você também pode usar npm run watch para recompilar automaticamente o servidor quando fizer alterações no código.

Localização do Arquivo de Configuração

Para desenvolvimento local, coloque seu arquivo etsy_mcp_settings.json no diretório raiz do projeto (no mesmo nível de package.json). O servidor detectará e carregará automaticamente.

Executando o Servidor

Após a compilação, inicie o servidor com:

npm start

Importante: Este servidor MCP se comunica via stdio e foi projetado para ser conectado por clientes MCP (como Claude Desktop, Cline ou outros aplicativos compatíveis com MCP). Quando executado diretamente, ele iniciará e aguardará mensagens do protocolo MCP. Para testar a funcionalidade, use o MCP Inspector (veja a seção Depuração) ou conecte-o a um cliente MCP.

Integração com Cliente MCP

Para usar este servidor com um cliente MCP, você normalmente precisa:

  1. Claude Desktop: Adicione a configuração do servidor às configurações do seu Claude Desktop
  2. Cline: Configure o servidor nas configurações do seu servidor MCP
  3. Outros Clientes MCP: Consulte a documentação do seu cliente para adicionar servidores MCP

O servidor será iniciado automaticamente pelo cliente MCP quando necessário.

Executando com Docker

Este é o método recomendado para implantação ou para executar o servidor em um ambiente padronizado.

Início Rápido com Docker

Opção 1: Compilar Localmente

docker build -t etsy-mcp-server .

Opção 2: Baixar do Registro (quando disponível)

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

Localização do Arquivo de Configuração para Docker

Para uso com Docker, seu arquivo etsy_mcp_settings.json deve estar localizado no mesmo diretório onde você executa o comando docker run. O ./ no mount de volume refere-se ao seu diretório de trabalho atual.

Comportamento do Contêiner

Importante: Servidores MCP não são serviços de segundo plano de longa duração. Quando você inicia o contêiner, ele irá:

  1. Carregar suas credenciais do Etsy (de variáveis de ambiente ou arquivo de configurações)
  2. Imprimir "Etsy MCP server running on stdio"
  3. Aguardar mensagens do protocolo MCP na entrada padrão (stdin)
  4. Sair após um curto período se nenhum cliente MCP se conectar

Este é o comportamento normal. O contêiner foi projetado para ser iniciado por clientes MCP quando necessário, não para ser executado continuamente como um servidor web.

Iniciando o Contêiner

Você pode fornecer suas credenciais do Etsy como variáveis de ambiente ou montando seu arquivo de configurações.

Opção 1: Usando Variáveis de Ambiente

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

Opção 2: Usando um Arquivo de Configurações

Crie um arquivo etsy_mcp_settings.json no seu diretório atual. Em seguida, monte-o no contêiner usando a flag -v:

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

Integração com Cliente MCP usando Docker

Para usar este contêiner Docker com clientes MCP:

  1. Claude Desktop: Configure o servidor para usar o comando Docker nas configurações do seu Claude Desktop
  2. Cline: Configure o comando Docker como comando de inicialização do seu servidor MCP
  3. Outros Clientes MCP: Use o comando Docker apropriado como executável do servidor

Exemplo de configuração de cliente MCP:

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

O cliente MCP iniciará automaticamente o contêiner quando precisar usar as ferramentas do Etsy e o interromperá quando terminar.

Docker Compose (Recomendado)

Para gerenciamento mais fácil, use Docker Compose:

  1. Copie .env.example para .env e preencha suas credenciais:

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

  2. Inicie com Docker Compose:

    docker-compose --profile production up

Implantação em Produção

Builds Multi-plataforma (para 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 .

Implantação no Registro:

# 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

Solução de Problemas com Docker

Problemas Comuns:

  1. O contêiner sai imediatamente: Este é o comportamento normal para servidores MCP quando nenhum cliente se conecta
  2. Permissão negada: Certifique-se de que o Docker tenha acesso adequado ao sistema de arquivos
  3. Arquivo de configurações não encontrado: Verifique se o caminho do mount de volume corresponde à localização do seu arquivo
  4. Variáveis de ambiente não carregadas: Verifique a sintaxe do arquivo .env e os nomes das variáveis

Comandos de Depuração:

# 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

Ferramentas disponíveis

getShop

Busca informações sobre uma loja. Argumento obrigatório: shop_id.

getMe

Retorna informações básicas sobre o usuário autenticado, incluindo user_id e shop_id. Este endpoint não aceita argumentos.

getListingsByShop

Lista os anúncios de uma loja. Suporta um parâmetro opcional state (ex.: active, draft). Requer shop_id.

createDraftListing

Cria um novo anúncio físico em rascunho usando POST /v3/application/shops/{shop_id}/listings. A ferramenta aceita todos os campos suportados pelo endpoint createDraftListing do Etsy.

uploadListingImage

Envia uma imagem para um anúncio. Requer shop_id, listing_id e image_path. (A implementação é atualmente um placeholder.)

updateListing

Atualiza um anúncio existente. Requer shop_id e listing_id. Campos opcionais incluem title, description e price.

getShopReceipts

Recupera os recibos de uma loja. Requer shop_id.

getShopSections

Recupera a lista de seções de uma loja. Requer shop_id.

getShopSection

Recupera uma única seção de loja por shop_id e shop_section_id.

getSellerTaxonomyNodes

Recupera a hierarquia completa dos nós de taxonomia do vendedor.

getPropertiesByTaxonomyId

Lista as propriedades de produto suportadas para um nó de taxonomia específico. Requer taxonomy_id.

Depuração

Usando o MCP Inspector

Para depurar e testar a funcionalidade do servidor, use o MCP Inspector com a configuração de desenvolvimento local:

npm run inspector

O inspector irá:

  1. Iniciar um servidor proxy e uma interface web
  2. Iniciar o servidor MCP compilado localmente
  3. Fornecer uma URL para visualizar logs de comunicação e testar ferramentas interativamente

Importante: O MCP Inspector só funciona com a configuração de desenvolvimento local, não com Docker. Isso ocorre porque:

  • Os contêineres Docker iniciam e saem rapidamente quando nenhum cliente MCP se conecta
  • O inspector precisa de acesso direto ao processo do servidor
  • O isolamento de rede impede que o inspector se comunique com servidores em contêineres

Fluxo de Trabalho de Depuração Recomendado

  1. Para Desenvolvimento e Testes: Use o desenvolvimento local com o MCP Inspector

    npm run build
npm run inspector

  2. Para Implantação: Use Docker com clientes MCP

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

Esta abordagem oferece o melhor dos dois mundos: depuração interativa localmente e implantação confiável com Docker.