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

2. 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"
      }
    }
  }
}

3. Reinicia Cursor completamente

4. 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

2. 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"
      }
    }
  }
}

3. 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