{
  "markdown": "# buda-mcp\n\n[![npm version](https://img.shields.io/npm/v/@guiie/buda-mcp)](https://www.npmjs.com/package/@guiie/buda-mcp)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Node.js >=18](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org/)\n\nMCP server for [Buda.com](https://www.buda.com/) — the leading cryptocurrency exchange in Chile, Colombia, and Peru. Gives any MCP-compatible AI assistant live access to market data, order books, trade history, spreads, technical indicators, and price simulation — no account or API key required.\n\n---\n\n## Quick Start\n\n```bash\nnpx @guiie/buda-mcp\n```\n\nOr install permanently:\n\n```bash\nnpm install -g @guiie/buda-mcp\nbuda-mcp\n```\n\n---\n\n## Install in your MCP client\n\n### Claude Code\n\n```bash\nclaude mcp add buda-mcp -- npx -y @guiie/buda-mcp\n```\n\n### Claude Desktop (`claude_desktop_config.json`)\n\n```json\n{\n  \"mcpServers\": {\n    \"buda-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@guiie/buda-mcp\"]\n    }\n  }\n}\n```\n\n### Cursor (`~/.cursor/mcp.json`)\n\n```json\n{\n  \"mcpServers\": {\n    \"buda-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@guiie/buda-mcp\"]\n    }\n  }\n}\n```\n\n---\n\n## Tools\n\nAll tools are public — no API key or account required.\n\n#### `get_market_summary` ⭐ Start here\nOne-call summary: last price, bid/ask, spread %, 24h volume, price change, and `liquidity_rating` (`high` / `medium` / `low`). Best first tool when a user asks about any specific market.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `market_id` | string | Yes | Market ID (e.g. `BTC-CLP`). |\n\n---\n\n#### `get_markets`\nList all trading pairs on Buda.com, or get details for a specific market (fees, minimum order size, discount tiers).\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `market_id` | string | No | Market ID (e.g. `BTC-CLP`). Omit to list all markets. |\n\n---\n\n#### `get_ticker`\nCurrent snapshot: last price, best bid/ask, 24h volume, and price change over 24h and 7d.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `market_id` | string | Yes | Market ID (e.g. `BTC-CLP`, `ETH-COP`). |\n\n---\n\n#### `get_orderbook`\nCurrent order book: sorted bids and asks as `{price, amount}` objects.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `market_id` | string | Yes | Market ID. |\n| `limit` | number | No | Max price levels per side (default: all). |\n\n---\n\n#### `get_trades`\nRecent trade history as typed objects: `{timestamp_ms, amount, price, direction}`.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `market_id` | string | Yes | Market ID. |\n| `limit` | number | No | Number of trades (default 50, max 100). |\n| `timestamp` | number | No | Unix seconds — returns trades older than this (pagination). |\n\n---\n\n#### `get_market_volume`\n24h and 7-day transacted volume by side (bid = buys, ask = sells).\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `market_id` | string | Yes | Market ID. |\n\n---\n\n#### `get_spread`\nBid/ask spread: absolute value and percentage of the ask price.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `market_id` | string | Yes | Market ID. |\n\n---\n\n#### `compare_markets`\nSide-by-side ticker data for all pairs of a given base currency across all quote currencies.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `base_currency` | string | Yes | Base currency (e.g. `BTC`, `ETH`). |\n\n---\n\n#### `get_price_history`\nOHLCV candles aggregated from raw trade history (Buda has no native candlestick endpoint). Supports `5m`, `15m`, `30m`, `1h`, `4h`, `1d` periods.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `market_id` | string | Yes | Market ID. |\n| `period` | string | No | `5m` / `15m` / `30m` / `1h` / `4h` / `1d` (default `1h`). |\n| `limit` | number | No | Raw trades to fetch before aggregation (default 100, max 1000). |\n\n---\n\n#### `get_arbitrage_opportunities`\nDetects cross-country price discrepancies for an asset across Buda's CLP, COP, and PEN markets, normalized to USDC.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `base_currency` | string | Yes | e.g. `BTC`. |\n| `threshold_pct` | number | No | Minimum discrepancy to report (default 0.5). |\n\n---\n\n#### `simulate_order`\nSimulates a buy or sell order using live ticker data — no order is ever placed. Returns `estimated_fill_price`, `fee_amount`, `total_cost`, `slippage_vs_mid_pct`. All responses include `simulation: true`.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `market_id` | string | Yes | Market ID. |\n| `side` | `buy` \\| `sell` | Yes | Order side. |\n| `amount` | number | Yes | Order size in base currency. |\n| `price` | number | No | Omit for market order simulation. |\n\n---\n\n#### `calculate_position_size`\nKelly-style position sizing from capital, risk %, entry, and stop-loss. Fully client-side — no API call.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `market_id` | string | Yes | Market ID (for context). |\n| `capital` | number | Yes | Total capital to size from. |\n| `risk_pct` | number | Yes | % of capital to risk (0.1–10). |\n| `entry_price` | number | Yes | Entry price. |\n| `stop_loss_price` | number | Yes | Stop-loss price. |\n\n---\n\n#### `get_market_sentiment`\nComposite sentiment score (−100 to +100) from three components: 24h price variation (40%), volume vs 7-day average (35%), spread vs market-type baseline (25%). Returns `score`, `label`, `component_breakdown`, and a `disclaimer`.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `market_id` | string | Yes | Market ID. |\n\n---\n\n#### `get_technical_indicators`\nRSI (14), MACD (12/26/9), Bollinger Bands (20, 2σ), SMA 20, SMA 50 — computed server-side from Buda trade history (no external libraries). Returns signal interpretations and a structured warning if fewer than 20 candles are available. Includes `disclaimer`.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `market_id` | string | Yes | Market ID. |\n| `period` | string | No | `1h` / `4h` / `1d` (default `1h`). |\n| `limit` | number | No | Raw trades to fetch (500–1000). |\n\n---\n\n#### `get_real_quotation`\nReturns a real-time quotation for a given order amount and direction, showing exact fill price, fee, and balance changes without placing an order.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `market_id` | string | Yes | Market ID. |\n| `type` | `Bid` \\| `Ask` | Yes | Order side. |\n| `amount` | number | Yes | Order size in base currency. |\n| `limit_price` | number | No | Limit price for limit quotations. |\n\n---\n\n#### `get_available_banks`\nLists available banks for fiat deposits/withdrawals in a given currency's country.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `currency` | string | Yes | Fiat currency code (e.g. `CLP`, `COP`, `PEN`). |\n\n---\n\n## MCP Resources\n\nIn addition to tools, the server exposes MCP Resources that clients can read directly:\n\n| URI | Description |\n|-----|-------------|\n| `buda://markets` | JSON list of all Buda.com markets |\n| `buda://ticker/{market}` | JSON ticker for a specific market (e.g. `buda://ticker/BTC-CLP`) |\n| `buda://summary/{market}` | Full market summary with liquidity rating (e.g. `buda://summary/BTC-CLP`) |\n\n---\n\n## Markets covered\n\n| Quote | Country | Sample pairs |\n|-------|---------|-------------|\n| CLP | Chile | BTC-CLP, ETH-CLP, SOL-CLP |\n| COP | Colombia | BTC-COP, ETH-COP, SOL-COP |\n| PEN | Peru | BTC-PEN, ETH-PEN |\n| USDC | USD-pegged | BTC-USDC, USDT-USDC |\n| BTC | Cross | ETH-BTC, LTC-BTC, BCH-BTC |\n\n---\n\n## Build from source\n\n```bash\ngit clone https://github.com/gtorreal/buda-mcp.git\ncd buda-mcp\nnpm install\nnpm run build\nnode dist/index.js        # stdio (for MCP clients)\nnode dist/http.js         # HTTP on port 3000 (for Railway / hosted)\n```\n\nRun tests:\n\n```bash\nnpm run test:unit        # 100 unit tests, no network required\nnpm run test:integration # live API tests (skips if unreachable)\nnpm test                 # both\n```\n\n---\n\n## HTTP / Railway deployment\n\nThe `dist/http.js` entrypoint runs an Express server with:\n- `POST /mcp` — Streamable HTTP MCP transport\n- `GET /mcp` — SSE streaming transport\n- `GET /health` — health check (`{ status }`)\n- `GET /.well-known/mcp/server-card.json` — Smithery-compatible static tool manifest\n\n### Environment variables\n\n| Variable | Required | Description |\n|---|---|---|\n| `PORT` | No | HTTP listen port (default: `3000`) |\n| `MCP_RATE_LIMIT` | No | Max requests per IP per minute on `/mcp` (default: `120`) |\n| `TRUST_PROXY_HOPS` | No | Number of reverse-proxy hops to trust for `X-Forwarded-For` (default: `1`). |\n\n---\n\n## Security\n\nThe server exposes only public Buda.com API endpoints. No credentials are accepted or stored. Input validation is applied to all tool parameters to prevent prompt injection. Error messages are sanitized — internal details (paths, upstream errors) are logged to stderr only and never returned to callers.\n\n### Reporting vulnerabilities\n\nPlease report security issues privately via [GitHub Security Advisories](https://github.com/gtorreal/buda-mcp/security/advisories/new) — not as public issues. See [SECURITY.md](SECURITY.md) for the full disclosure policy.\n\n---\n\n## Project structure\n\n```\nsrc/\n  client.ts                   BudaClient (HTTP + 429 retry)\n  cache.ts                    In-memory TTL cache with in-flight deduplication\n  types.ts                    TypeScript types for Buda API responses\n  validation.ts               validateMarketId(), validateCurrency()\n  utils.ts                    flattenAmount(), aggregateTradesToCandles(), getLiquidityRating()\n  version.ts                  Single source of truth for version string\n  index.ts                    stdio MCP server entrypoint\n  http.ts                     HTTP/SSE MCP server entrypoint\n  tools/\n    markets.ts                get_markets\n    ticker.ts                 get_ticker\n    orderbook.ts              get_orderbook\n    trades.ts                 get_trades\n    volume.ts                 get_market_volume\n    spread.ts                 get_spread\n    compare_markets.ts        compare_markets\n    price_history.ts          get_price_history\n    arbitrage.ts              get_arbitrage_opportunities\n    market_summary.ts         get_market_summary\n    simulate_order.ts         simulate_order\n    calculate_position_size.ts calculate_position_size\n    market_sentiment.ts       get_market_sentiment\n    technical_indicators.ts   get_technical_indicators\n    banks.ts                  get_available_banks\n    quotation.ts              get_real_quotation\nmarketplace/\n  cursor-mcp.json             Cursor MCP config example\n  claude-listing.md           Claude registry listing\n  openapi.yaml                OpenAPI spec (GPT Actions / HTTP wrapper)\n  gemini-tools.json           Gemini function declarations\n```\n\n---\n\n## Documentation\n\nAgent context: [AGENTS.md](AGENTS.md) | Operational notes: [docs/PROJECT_MEMORY.md](docs/PROJECT_MEMORY.md) | Changelog: [CHANGELOG.md](CHANGELOG.md) | Security: [SECURITY.md](SECURITY.md)\n\n---\n\n## License\n\nMIT — [Buda.com API docs](https://api.buda.com/en/)\n",
  "bytes": 11673,
  "sha": "b0789d581c7fbe13512ed88a110c0eca05fb5aeabbadd2f249f00b0bf96162f8",
  "repo_slug": "gtorreal/buda-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_gtorreal_buda_mcp_3b87e852/readme"
}