MCP Servers - Docker

Servidores MCP (Model Context Protocol) containerizados para uso com Claude Code, Cursor, VS Code e outros clientes MCP.

Estrutura

mcp/
├── mcp-figma/       # figma-developer-mcp (Framelink)
│   └── Dockerfile
├── mcp-jira/        # @aashari/mcp-server-atlassian-jira + mcp-proxy
│   └── Dockerfile
├── mcp-jam/         # mcp-remote → https://mcp.jam.dev/mcp
│   └── Dockerfile
├── docker-compose.yml
├── .env.example
└── .env             # suas credenciais (git ignored)

Pre-requisitos

• Docker Desktop instalado e rodando
• Credenciais de API para cada servico (veja abaixo)

Setup

1. Clonar e configurar credenciais

cd ~/mcp
cp .env.example .env

Edite o .env com suas credenciais:

| Variavel | Onde obter | |----------|-----------| | FIGMA_API_KEY | Figma > Settings > Personal Access Tokens — marque o scope current_user:read | | ATLASSIAN_SITE_URL | URL do seu workspace (ex: https://sua-empresa.atlassian.net) | | ATLASSIAN_USER_EMAIL | Seu email da conta Atlassian | | ATLASSIAN_API_TOKEN | Atlassian > API Tokens |

2. Subir os containers

docker compose up -d --build

3. Autenticar o Jam (apenas na primeira vez)

O Jam usa OAuth e precisa de autorizacao manual apenas na primeira execucao. O token e salvo em um volume Docker (jam-auth) e persiste entre rebuilds.

docker logs mcp-jam

Copie a URL que aparece no log (https://api.jam.dev/oauth/authorize?...) e abra no browser. Faca login na sua conta Jam e autorize. Voce vera "Authorization successful!" no browser.

Nota sobre macOS: O mcp-remote tem 127.0.0.1 hardcoded no callback server do OAuth. O Dockerfile aplica um patch com sed trocando para 0.0.0.0, permitindo que o port mapping do Docker funcione no macOS (onde o Docker roda numa VM). Sem esse patch, o redirect do OAuth nao alcanca o container.

Persistencia do token: O volume jam-auth armazena os tokens OAuth em /home/mcp/.mcp-auth. Isso significa que voce nao precisa autenticar novamente ao fazer docker compose down/up ou --build. O token so sera perdido se o volume for removido manualmente (docker volume rm mcp_jam-auth) ou ao trocar de maquina.

Container em Restarting: O Jam pode aparecer com status "Restarting" — isso e normal. O mcp-remote roda em modo stdio, conecta, faz o proxy, e encerra quando o stdin fecha. O restart: unless-stopped mantem ele disponivel para novas conexoes.

Endpoints

| Servico | Endpoint | Protocolo | |---------|----------|-----------| | Figma | http://localhost:3000/mcp | StreamableHTTP | | Jira | http://localhost:3001/sse | SSE | | Jam | http://localhost:3002 | stdio via mcp-remote |

Configuracao no cliente MCP

Claude Code

claude mcp add figma --transport sse http://localhost:3000/sse
claude mcp add jira --transport sse http://localhost:3001/sse

Cursor / VS Code (settings JSON)

{
  "mcpServers": {
    "figma": {
      "url": "http://localhost:3000/mcp"
    },
    "jira": {
      "url": "http://localhost:3001/sse"
    }
  }
}

Seguranca

• .env no .gitignore — credenciais nunca sao commitadas
• .dockerignore em cada servico — .env nao vaza para dentro das imagens
• Portas em 127.0.0.1 — servicos acessiveis apenas localmente, nao expostos na rede
• Usuario non-root — todos os containers rodam com usuario mcp sem privilegios

Comandos uteis

# Ver status dos containers
docker compose ps

# Ver logs de um servico
docker logs mcp-figma
docker logs mcp-jira
docker logs mcp-jam

# Parar tudo
docker compose down

# Rebuild apos mudancas
docker compose up -d --build

# Rebuild um servico especifico
docker compose up -d --build mcp-figma

Troubleshooting

Container em "Restarting"

Verifique os logs: docker logs <container>. Causas comuns:

• Figma: FIGMA_API_KEY nao configurada no .env, ou token sem o scope current_user:read
• Jira: credenciais Atlassian invalidas ou .env nao preenchido
• Jam: normal em modo stdio (veja nota acima)

Jam OAuth nao completa

Se o redirect do OAuth nao funciona:

1. Verifique se a porta 8943 esta exposta: curl http://localhost:8943/
2. Se retornar erro de conexao, reconstrua o container: docker compose up -d --build mcp-jam
3. Pegue a nova URL de autorizacao nos logs: docker logs mcp-jam

Jam pedindo OAuth novamente

Se o Jam pedir autenticacao apos um rebuild, o volume pode ter sido removido. Verifique:

docker volume ls | grep jam-auth

Se nao existir, suba novamente e refaca o OAuth (passo 3 do Setup).

Trocar de maquina

1. Copie a pasta ~/mcp/ inteira para a nova maquina
2. Edite o .env com as credenciais (ou copie de forma segura)
3. docker compose up -d --build
4. Refaca o OAuth do Jam (passo 3 do Setup) — o volume nao e portavel entre maquinas