Wallbit MCP

Servidor MCP (Model Context Protocol) para interactuar con la API de Wallbit desde asistentes de IA como Claude y Cursor.

Soporta dos modos de ejecución:

• Local (stdio): Para uso directo con Cursor/Claude Desktop
• Servidor HTTP (SSE): Para deployment en EC2 u otros servidores

Requisitos

• Node.js 20+
• npm o yarn
• API Key de Wallbit

Instalación

# Clonar el repositorio
git clone https://github.com/Wallbit/wallbit-mcp
cd wallbit-mcp

# Instalar dependencias
npm install

# Compilar el proyecto
npm run build

Variables de Entorno

| Variable | Descripción | Requerido | | ---------- | ----------------------------------------------------------- | --------- | | BASE_URL | URL base de la API de Wallbit | Sí | | API_KEY | API Key de Wallbit (fallback cuando no se envía por header) | No\* | | PORT | Puerto del servidor HTTP (default: 8080) | No |

\* En modo servidor HTTP la API key puede enviarse por header (ver más abajo). En modo stdio (local) es obligatoria por env.

API Key dinámica (modo servidor HTTP)

Cuando el MCP se ejecuta como servidor HTTP, puedes enviar la API key de Wallbit por petición en el header, así cada cliente puede usar su propia key sin tocar variables de entorno:

• Header: X-API-Key (o x-api-key)
• Valor: Tu API Key de Wallbit

Si no envías este header, el servidor usará la variable de entorno API_KEY. Ejemplo de configuración en Cursor contra un MCP remoto:

{
  "mcpServers": {
    "wallbit": {
      "url": "https://mcp.wallbit.com/mcp",
      "headers": {
        "X-API-Key": "your-wallbit-api-key"
      }
    }
  }
}

Modo Local (Cursor/Claude Desktop)

Uso con Cursor

1. Abre Settings → Cursor Settings → MCP

1. Edita el archivo ~/.cursor/mcp.json:

{
  "mcpServers": {
    "wallbit": {
      "command": "node",
      "args": ["/ruta/completa/a/wallbit-mcp/dist/stdio.js"],
      "env": {
        "BASE_URL": "https://api.wallbit.io",
        "API_KEY": "your-api-key"
      }
    }
  }
}

1. Reinicia Cursor completamente

1. Verifica que el servidor aparezca con indicador verde en la configuración de MCP

Uso con Claude Desktop

1. Edita el archivo de configuración de Claude Desktop:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

1. Agrega la configuración:

{
  "mcpServers": {
    "wallbit": {
      "command": "node",
      "args": ["/ruta/completa/a/wallbit-mcp/dist/stdio.js"],
      "env": {
        "BASE_URL": "https://api.wallbit.io",
        "API_KEY": "your-api-key"
      }
    }
  }
}

1. Reinicia Claude Desktop

---

Modo Servidor (EC2 / Remoto)

1. Preparar el servidor EC2

# Conectar a tu EC2
ssh -i tu-key.pem ec2-user@tu-ip-publica

# Instalar Node.js (Amazon Linux 2)
curl -fsSL https://rpm.nodesource.com/setup_20.x | sudo bash -
sudo yum install -y nodejs

# O en Ubuntu
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# Clonar el repositorio
git clone https://github.com/Wallbit/wallbit-mcp
cd wallbit-mcp

# Instalar y compilar
npm install
npm run build

2. Configurar variables de entorno

Crear archivo .env en el directorio del proyecto:

# Wallbit API
BASE_URL=https://api.wallbit.io
API_KEY=your-api-key

# Server
PORT=8080

# Token de autenticación para clientes MCP (genera uno seguro)
API_KEY=

Generar un token seguro:

openssl rand -hex 32

3. Ejecutar con PM2 (recomendado para producción)

# Instalar PM2
sudo npm install -g pm2

# Iniciar el servidor HTTP
pm2 start dist/http.js --name wallbit-mcp

# Ver logs
pm2 logs wallbit-mcp

# Configurar inicio automático
pm2 startup
pm2 save

4. Configurar Security Group en AWS

Abrir los siguientes puertos inbound:

| Puerto | Protocolo | Fuente | Descripción | | ------ | --------- | --------- | ------------------------ | | 22 | TCP | Tu IP | SSH | | 8080 | TCP | 0.0.0.0/0 | MCP Server (o usa Nginx) | | 443 | TCP | 0.0.0.0/0 | HTTPS (si usas Nginx) |

5. Configurar Nginx con HTTPS (recomendado)

# Instalar Nginx y Certbot
sudo amazon-linux-extras install nginx1 -y
sudo yum install certbot python3-certbot-nginx -y

# O en Ubuntu
sudo apt install nginx certbot python3-certbot-nginx -y

Crear /etc/nginx/conf.d/wallbit-mcp.conf:

server {
    listen 80;
    server_name tu-dominio.com;

    location / {
        proxy_pass http://localhost:8080;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_cache_bypass $http_upgrade;

        # Configuración importante para SSE
        proxy_buffering off;
        proxy_cache off;
        proxy_read_timeout 86400s;
        proxy_send_timeout 86400s;
    }
}

# Obtener certificado SSL
sudo certbot --nginx -d tu-dominio.com

# Reiniciar Nginx
sudo systemctl restart nginx

6. Conectar Cursor al servidor remoto

Edita ~/.cursor/mcp.json:

{
  "mcpServers": {
    "wallbit": {
      "url": "https://tu-dominio.com/sse",
      "headers": {
        "X-API-Key": "your-wallbit-api-key"
      }
    }
  }
}

Opcional: si el servidor tiene API_KEY en el entorno, no hace falta enviar X-API-Key en los headers.

Sin HTTPS (solo para testing):

{
  "mcpServers": {
    "wallbit": {
      "url": "http://your-public-ip:8080/sse",
      "headers": {
        "X-API-Key": "tu-wallbit-api-key"
      }
    }
  }
}

Usando Docker

FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY dist ./dist
EXPOSE 8080
ENV PORT=8080
CMD ["node", "dist/http.js"]

# Compilar imagen
npm run build
docker build -t wallbit-mcp .

# Ejecutar
docker run -d \
  -p 8080:8080 \
  -e BASE_URL=https://api.wallbit.io \
  -e API_KEY=tu-wallbit-api-key \
  --name wallbit-mcp \
  wallbit-mcp

---

Tools Disponibles

La especificación OpenAPI vive en docs/openapi-public-api.json y se mantiene sincronizada con api-wallbit.

| Tool | Endpoint | Método | Descripción | | ---- | -------- | ------ | ----------- | | get_checking_balance | /balance/checking | GET | Balance cuenta checking (DEFAULT) | | get_stocks_balance | /balance/stocks | GET | Portfolio de inversión | | list_transactions | /transactions | GET | Historial con filtros y paginación | | create_trade | /trades | POST | Compra/venta (MARKET, LIMIT, STOP, STOP_LIMIT) | | get_public_fee_settings | /fees | POST | Comisiones por tier (tipo TRADE) | | get_account_details | /account-details | GET | Datos bancarios ACH/SEPA | | get_wallets | /wallets | GET | Direcciones crypto USDT/USDC | | get_exchange_rate | /rates | GET | Tipo de cambio entre monedas | | list_assets | /assets | GET | Listar assets con categoría/búsqueda | | get_asset | /assets/{symbol} | GET | Detalle de un asset | | internal_operation | /operations/internal | POST | Transferir DEFAULT ↔ INVESTMENT | | list_cards | /cards | GET | Tarjetas activas/suspendidas | | update_card_status | /cards/{uuid}/status | PATCH | Bloquear/desbloquear tarjeta | | revoke_api_key | /api-key | DELETE | Revocar la API key actual |

list_transactions — filtros

| Nombre | Tipo | Descripción | | ------ | ---- | ----------- | | page, limit | number | Paginación (limit: 10, 20 o 50) | | status, type | string | Estado y tipo de transacción | | currency | enum | USD, EUR, ARS, MXN, USDC, USDT, etc. | | from_date, to_date | string | Rango de fechas (Y-m-d) | | from_amount, to_amount | number | Rango de montos |

create_trade — tipos de orden

• MARKET, LIMIT, STOP, STOP_LIMIT
• amount o shares (no ambos)
• limit_price, stop_price, time_in_force (DAY/GTC) según el tipo

---

Ejemplos de Conversación

Consultar balance completo

Usuario: ¿Cuánto dinero tengo en Wallbit?

Asistente: Tienes:
- Cuenta Corriente: $7,469.89 USD
- Cuenta de Inversiones: $998.61 USD en efectivo
- Acciones: AAPL (0.077), TSLA (0.007), YPF (0.30)

Realizar una compra

Usuario: Quiero invertir $500 en Apple

Asistente: Voy a crear una orden de compra de $500 en AAPL...
✅ Orden ejecutada exitosamente.

Consultar un asset

Usuario: ¿Cómo está Tesla hoy?

Asistente: Tesla (TSLA) está cotizando a $XXX.XX USD
- Cambio diario: +X.XX%
- Volumen: X,XXX,XXX

---

Estructura del Proyecto

wallbit-mcp/
├── docs/
│   └── openapi-public-api.json   # Spec OpenAPI (fuente de verdad para tools)
├── src/
│   ├── lib/
│   │   └── api.ts                # Cliente HTTP para Wallbit API
│   ├── middleware/
│   │   └── auth.ts               # Middleware de autenticación
│   └── tools/                    # Una tool por operationId del OpenAPI
├── dist/
│   ├── stdio.js                  # Entry point para modo local
│   └── http.js                   # Entry point para modo servidor
├── package.json
├── tsconfig.json
├── Dockerfile
└── README.md

Desarrollo

# Modo desarrollo con hot reload
npm run dev

# Compilar para producción
npm run build

# Ejecutar modo local (stdio)
npm run start:stdio

# Ejecutar modo servidor (HTTP)
npm start

Troubleshooting

El servidor no responde

• Verifica que las variables de entorno estén configuradas
• Revisa los logs: pm2 logs wallbit-mcp

Error de autenticación

• Verifica que el token en Cursor coincida con API_KEY
• El header debe ser Authorization: Bearer <token>

Timeout en SSE

• Asegúrate de que Nginx tenga proxy_buffering off
• Verifica que el Security Group permita el tráfico

Licencia

MIT