buda-mcp

Servidor MCP para Buda.com — el exchange de criptomonedas líder en Chile, Colombia y Perú. Proporciona a cualquier asistente de IA compatible con MCP acceso en vivo a datos de mercado, libros de órdenes, historial de operaciones, spreads, indicadores técnicos y simulación de precios; no requiere cuenta ni clave API.

Inicio rápido

npx @guiie/buda-mcp

O instálalo de forma permanente:

npm install -g @guiie/buda-mcp
buda-mcp

Instalar en tu cliente MCP

Claude Code

claude mcp add buda-mcp -- npx -y @guiie/buda-mcp

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "buda-mcp": {
      "command": "npx",
      "args": ["-y", "@guiie/buda-mcp"]
    }
  }
}

Cursor (~/.cursor/mcp.json)

{
  "mcpServers": {
    "buda-mcp": {
      "command": "npx",
      "args": ["-y", "@guiie/buda-mcp"]
    }
  }
}

Herramientas

Todas las herramientas son públicas; no se requiere clave API ni cuenta.

get_market_summary ⭐ Empieza aquí

Resumen en una sola llamada: último precio, bid/ask, % de spread, volumen de 24h, cambio de precio y liquidity_rating (high / medium / low). La mejor herramienta para empezar cuando un usuario pregunta por un mercado específico.

get_markets

Lista todos los pares de trading en Buda.com u obtén detalles de un mercado específico (comisiones, tamaño mínimo de orden, niveles de descuento).

get_ticker

Instantánea actual: último precio, mejor bid/ask, volumen de 24h y cambio de precio en 24h y 7d.

get_orderbook

Libro de órdenes actual: bids y asks ordenados como objetos {price, amount}.

get_trades

Historial de operaciones recientes como objetos tipados: {timestamp_ms, amount, price, direction}.

get_market_volume

Volumen transaccionado en 24h y 7 días por lado (bid = compras, ask = ventas).

get_spread

Spread bid/ask: valor absoluto y porcentaje del precio ask.

compare_markets

Datos de ticker comparativos para todos los pares de una moneda base dada a través de todas las monedas de cotización.

get_price_history

Velas OHLCV agregadas a partir del historial de operaciones crudo (Buda no tiene un endpoint nativo de velas). Soporta periodos de 5m, 15m, 30m, 1h, 4h, 1d.

get_arbitrage_opportunities

Detecta discrepancias de precios entre países para un activo en los mercados CLP, COP y PEN de Buda, normalizados a USDC.

simulate_order

Simula una orden de compra o venta usando datos de ticker en vivo; nunca se coloca una orden real. Devuelve estimated_fill_price, fee_amount, total_cost, slippage_vs_mid_pct. Todas las respuestas incluyen simulation: true.

calculate_position_size

Dimensionamiento de posición estilo Kelly a partir de capital, % de riesgo, entrada y stop-loss. Totalmente del lado del cliente; no hay llamada a API.

get_market_sentiment

Puntaje de sentimiento compuesto (−100 a +100) a partir de tres componentes: variación de precio en 24h (40%), volumen vs promedio de 7 días (35%), spread vs línea base del tipo de mercado (25%). Devuelve score, label, component_breakdown y un disclaimer.

get_technical_indicators

RSI (14), MACD (12/26/9), Bandas de Bollinger (20, 2σ), SMA 20, SMA 50 — calculados en el servidor a partir del historial de operaciones de Buda (sin librerías externas). Devuelve interpretaciones de señales y una advertencia estructurada si hay menos de 20 velas disponibles. Incluye disclaimer.

get_real_quotation

Devuelve una cotización en tiempo real para un monto y dirección de orden dados, mostrando el precio de ejecución exacto, comisión y cambios de saldo sin colocar una orden.

get_available_banks

Lista los bancos disponibles para depósitos/retiros fiat en el país de una moneda dada.

Recursos MCP

Además de las herramientas, el servidor expone Recursos MCP que los clientes pueden leer directamente:

Mercados cubiertos

Construir desde el código fuente

git clone https://github.com/gtorreal/buda-mcp.git
cd buda-mcp
npm install
npm run build
node dist/index.js        # stdio (for MCP clients)
node dist/http.js         # HTTP on port 3000 (for Railway / hosted)

Ejecutar pruebas:

npm run test:unit        # 100 unit tests, no network required
npm run test:integration # live API tests (skips if unreachable)
npm test                 # both

Despliegue HTTP / Railway

El punto de entrada dist/http.js ejecuta un servidor Express con:

• POST /mcp — Transporte MCP HTTP transmitible

• GET /mcp — Transporte de transmisión SSE

• GET /health — verificación de estado ({ status })

• GET /.well-known/mcp/server-card.json — manifiesto de herramientas estático compatible con Smithery

Variables de entorno

Seguridad

El servidor expone solo endpoints públicos de la API de Buda.com. No se aceptan ni almacenan credenciales. Se aplica validación de entrada a todos los parámetros de las herramientas para prevenir inyecciones de prompts. Los mensajes de error están saneados; los detalles internos (rutas, errores upstream) se registran solo en stderr y nunca se devuelven a los llamadores.

Reportar vulnerabilidades

Por favor, reporta problemas de seguridad de forma privada a través de GitHub Security Advisories — no como problemas públicos. Consulta SECURITY.md para la política completa de divulgación.

Estructura del proyecto

src/
  client.ts                   BudaClient (HTTP + 429 retry)
  cache.ts                    In-memory TTL cache with in-flight deduplication
  types.ts                    TypeScript types for Buda API responses
  validation.ts               validateMarketId(), validateCurrency()
  utils.ts                    flattenAmount(), aggregateTradesToCandles(), getLiquidityRating()
  version.ts                  Single source of truth for version string
  index.ts                    stdio MCP server entrypoint
  http.ts                     HTTP/SSE MCP server entrypoint
  tools/
    markets.ts                get_markets
    ticker.ts                 get_ticker
    orderbook.ts              get_orderbook
    trades.ts                 get_trades
    volume.ts                 get_market_volume
    spread.ts                 get_spread
    compare_markets.ts        compare_markets
    price_history.ts          get_price_history
    arbitrage.ts              get_arbitrage_opportunities
    market_summary.ts         get_market_summary
    simulate_order.ts         simulate_order
    calculate_position_size.ts calculate_position_size
    market_sentiment.ts       get_market_sentiment
    technical_indicators.ts   get_technical_indicators
    banks.ts                  get_available_banks
    quotation.ts              get_real_quotation
marketplace/
  cursor-mcp.json             Cursor MCP config example
  claude-listing.md           Claude registry listing
  openapi.yaml                OpenAPI spec (GPT Actions / HTTP wrapper)
  gemini-tools.json           Gemini function declarations

Licencia

MIT — Documentación de la API de Buda.com