Skip to main content
Glama
buda-mcp
by gtorreal

buda-mcp

npm version License: MIT Node.js >=18

MCP server for 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.


Quick Start

npx @guiie/buda-mcp

Or install permanently:

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

Related MCP server: market-data-mcp

Install in your MCP client

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"]
    }
  }
}

Tools

All tools are public — no API key or account required.

get_market_summary ⭐ Start here

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

Parameter

Type

Required

Description

market_id

string

Yes

Market ID (e.g. BTC-CLP).


get_markets

List all trading pairs on Buda.com, or get details for a specific market (fees, minimum order size, discount tiers).

Parameter

Type

Required

Description

market_id

string

No

Market ID (e.g. BTC-CLP). Omit to list all markets.


get_ticker

Current snapshot: last price, best bid/ask, 24h volume, and price change over 24h and 7d.

Parameter

Type

Required

Description

market_id

string

Yes

Market ID (e.g. BTC-CLP, ETH-COP).


get_orderbook

Current order book: sorted bids and asks as {price, amount} objects.

Parameter

Type

Required

Description

market_id

string

Yes

Market ID.

limit

number

No

Max price levels per side (default: all).


get_trades

Recent trade history as typed objects: {timestamp_ms, amount, price, direction}.

Parameter

Type

Required

Description

market_id

string

Yes

Market ID.

limit

number

No

Number of trades (default 50, max 100).

timestamp

number

No

Unix seconds — returns trades older than this (pagination).


get_market_volume

24h and 7-day transacted volume by side (bid = buys, ask = sells).

Parameter

Type

Required

Description

market_id

string

Yes

Market ID.


get_spread

Bid/ask spread: absolute value and percentage of the ask price.

Parameter

Type

Required

Description

market_id

string

Yes

Market ID.


compare_markets

Side-by-side ticker data for all pairs of a given base currency across all quote currencies.

Parameter

Type

Required

Description

base_currency

string

Yes

Base currency (e.g. BTC, ETH).


get_price_history

OHLCV candles aggregated from raw trade history (Buda has no native candlestick endpoint). Supports 5m, 15m, 30m, 1h, 4h, 1d periods.

Parameter

Type

Required

Description

market_id

string

Yes

Market ID.

period

string

No

5m / 15m / 30m / 1h / 4h / 1d (default 1h).

limit

number

No

Raw trades to fetch before aggregation (default 100, max 1000).


get_arbitrage_opportunities

Detects cross-country price discrepancies for an asset across Buda's CLP, COP, and PEN markets, normalized to USDC.

Parameter

Type

Required

Description

base_currency

string

Yes

e.g. BTC.

threshold_pct

number

No

Minimum discrepancy to report (default 0.5).


simulate_order

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

Parameter

Type

Required

Description

market_id

string

Yes

Market ID.

side

buy | sell

Yes

Order side.

amount

number

Yes

Order size in base currency.

price

number

No

Omit for market order simulation.


calculate_position_size

Kelly-style position sizing from capital, risk %, entry, and stop-loss. Fully client-side — no API call.

Parameter

Type

Required

Description

market_id

string

Yes

Market ID (for context).

capital

number

Yes

Total capital to size from.

risk_pct

number

Yes

% of capital to risk (0.1–10).

entry_price

number

Yes

Entry price.

stop_loss_price

number

Yes

Stop-loss price.


get_market_sentiment

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

Parameter

Type

Required

Description

market_id

string

Yes

Market ID.


get_technical_indicators

RSI (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.

Parameter

Type

Required

Description

market_id

string

Yes

Market ID.

period

string

No

1h / 4h / 1d (default 1h).

limit

number

No

Raw trades to fetch (500–1000).


get_real_quotation

Returns a real-time quotation for a given order amount and direction, showing exact fill price, fee, and balance changes without placing an order.

Parameter

Type

Required

Description

market_id

string

Yes

Market ID.

type

Bid | Ask

Yes

Order side.

amount

number

Yes

Order size in base currency.

limit_price

number

No

Limit price for limit quotations.


get_available_banks

Lists available banks for fiat deposits/withdrawals in a given currency's country.

Parameter

Type

Required

Description

currency

string

Yes

Fiat currency code (e.g. CLP, COP, PEN).


MCP Resources

In addition to tools, the server exposes MCP Resources that clients can read directly:

URI

Description

buda://markets

JSON list of all Buda.com markets

buda://ticker/{market}

JSON ticker for a specific market (e.g. buda://ticker/BTC-CLP)

buda://summary/{market}

Full market summary with liquidity rating (e.g. buda://summary/BTC-CLP)


Markets covered

Quote

Country

Sample pairs

CLP

Chile

BTC-CLP, ETH-CLP, SOL-CLP

COP

Colombia

BTC-COP, ETH-COP, SOL-COP

PEN

Peru

BTC-PEN, ETH-PEN

USDC

USD-pegged

BTC-USDC, USDT-USDC

BTC

Cross

ETH-BTC, LTC-BTC, BCH-BTC


Build from source

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)

Run tests:

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

HTTP / Railway deployment

The dist/http.js entrypoint runs an Express server with:

  • POST /mcp — Streamable HTTP MCP transport

  • GET /mcp — SSE streaming transport

  • GET /health — health check ({ status })

  • GET /.well-known/mcp/server-card.json — Smithery-compatible static tool manifest

Environment variables

Variable

Required

Description

PORT

No

HTTP listen port (default: 3000)

MCP_RATE_LIMIT

No

Max requests per IP per minute on /mcp (default: 120)

TRUST_PROXY_HOPS

No

Number of reverse-proxy hops to trust for X-Forwarded-For (default: 1).


Security

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

Reporting vulnerabilities

Please report security issues privately via GitHub Security Advisories — not as public issues. See SECURITY.md for the full disclosure policy.


Project structure

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

Documentation

Agent context: AGENTS.md | Operational notes: docs/PROJECT_MEMORY.md | Changelog: CHANGELOG.md | Security: SECURITY.md


License

MIT — Buda.com API docs

Available Tools

17 tools
calculate_position_sizeA

Calculates position size based on your capital, risk tolerance, entry price, and stop-loss. Determines how many units to buy or sell so that a stop-loss hit costs exactly risk_pct% of capital. Fully client-side — no API call is made. Example: 'How many BTC can I buy on BTC-CLP if I have 1,000,000 CLP, risk 2%, entry 80,000,000 CLP, stop at 78,000,000 CLP?'

Inputs: market_id (required), capital (required), risk_pct (required), entry_price (required), +1 more.

compare_marketsA

Returns side-by-side ticker data for all trading pairs of a given base currency across Buda.com's supported quote currencies (CLP, COP, PEN, BTC, USDC, ETH). All prices are floats; price_change_24h and price_change_7d are floats in percent (e.g. 1.23 means +1.23%). Example: 'In which country is Bitcoin currently most expensive on Buda?'

Inputs: base_currency (required).

get_arbitrage_opportunitiesA

Detects cross-country price discrepancies for a given asset across Buda's CLP, COP, and PEN markets, normalized to USDC. Fetches all relevant tickers, converts each local price to USDC using the current USDC-CLP / USDC-COP / USDC-PEN rates, then computes pairwise discrepancy percentages. Results above threshold_pct are returned sorted by opportunity size. Note: Buda taker fee is 0.8% per leg (~1.6% round-trip) — always deduct fees before acting on any discrepancy. Example: 'Is there an arbitrage opportunity for BTC between Chile and Peru right now?'

Inputs: base_currency (required), threshold_pct.

get_available_banksA

Returns banks available for deposits and withdrawals of a fiat currency on Buda.com. Returns an empty banks array (not an error) if the currency has no associated banks (e.g. crypto currencies or unsupported fiat currencies). Results are cached for 60 seconds. Example: 'Which banks can I use for CLP deposits?'

Inputs: currency (required).

get_marketsA

Lists all available trading pairs on Buda.com, or returns details for a specific market (base/quote currencies, taker/maker fees as decimals, minimum order size in base currency, and fee discount tiers). Omit market_id to get all ~26 markets at once. Example: 'What is the taker fee and minimum order size for BTC-CLP?'

Inputs: market_id.

get_market_sentimentA

Computes a composite sentiment score (−100 to +100) for a Buda.com market based on 24h price variation (40%), volume vs 7-day average (35%), and bid/ask spread vs baseline (25%). Returns a score, a label (bearish/neutral/bullish), and a full component breakdown. Example: 'Is the BTC-CLP market currently bullish or bearish?'

Inputs: market_id (required).

get_market_summaryA

One-call summary of everything relevant about a market: last price, best bid/ask, spread %, 24h volume, 24h and 7d price change, and a liquidity_rating ('high' / 'medium' / 'low' based on spread thresholds: < 0.3% = high, 0.3–1% = medium, > 1% = low). All prices and volumes are floats. Best first tool to call when a user asks about any specific market. Example: 'Give me a complete overview of the BTC-CLP market right now.'

Inputs: market_id (required).

get_market_volumeB

Returns 24h and 7-day transacted volume for a Buda.com market, split by buy (bid) and sell (ask) side. All volume values are floats in the base currency (e.g. BTC for BTC-CLP). Example: 'How much Bitcoin was sold on BTC-CLP in the last 24 hours?'

Inputs: market_id (required).

get_orderbookA

Returns the current order book for a Buda.com market as typed objects with float price and amount fields. Bids are sorted highest-price first; asks lowest-price first. Prices are in the quote currency; amounts are in the base currency. Example: 'What are the top 5 buy and sell orders for BTC-CLP right now?'

Inputs: market_id (required), limit.

get_price_historyA

IMPORTANT: Candles are aggregated client-side from raw trades (Buda has no native candlestick endpoint) — fetching more trades via the 'limit' parameter gives deeper history but slower responses. Returns OHLCV candles (open/high/low/close as floats in quote currency; volume as float in base currency) for periods 5m, 15m, 30m, 1h, 4h, or 1d. Candle timestamps are UTC bucket boundaries. Example: 'Show me the hourly BTC-CLP price chart for the past 24 hours.'

Inputs: market_id (required), period, limit.

get_real_quotationA

Gets a server-side price quotation for a buy or sell on Buda.com. Calls the Buda quotation API to compute an accurate fill estimate including fees, based on live order book state. Prefer this over simulate_order for accurate fee-tier-aware quotes. This is a POST (not idempotent) but does not place an order. Public endpoint — no API key required. Parameters: market_id, type ('Bid'|'Ask'), amount, optional limit price. Example: 'Get an accurate quote to sell 0.05 BTC on BTC-CLP.'

Inputs: market_id (required), type (required), amount (required), limit.

get_spreadA

Returns the best bid, best ask, absolute spread, and spread percentage for a Buda.com market. All prices are floats in the quote currency (e.g. CLP). spread_percentage is a float in percent (e.g. 0.15 means 0.15%). Use this to evaluate liquidity before placing a large order. Example: 'Is BTC-CLP liquid enough to buy 10M CLP without significant slippage?'

Inputs: market_id (required).

get_stable_liquidityA

Returns spread and market-impact slippage for all stablecoin markets on Buda.com (USDT-CLP, USDC-CLP, USDT-PEN, USDC-PEN, USDT-COP, USDC-COP, USDT-USDC, etc.). Slippage is computed by walking the live order book for five fixed USD notional sizes: 1k, 5k, 10k, 50k, and 100k. Positive buy_pct means you pay more than the best ask; negative sell_pct means you receive less than the best bid. null values indicate insufficient order book depth for that size. Example: 'How liquid are the stablecoin markets on Buda right now?'

Inputs: no named parameters.

get_technical_indicatorsA

Computes RSI (14), MACD (12/26/9), Bollinger Bands (20, 2σ), SMA 20, and SMA 50 from Buda trade history — no external data or libraries. Supports periods: 5m, 15m, 30m, 1h, 4h, 1d. Use shorter periods (5m/15m) for intraday analysis. Uses at least 500 trades for reliable results (set limit=1000 for maximum depth). Returns latest indicator values and signal interpretations (overbought/oversold, crossover, band position). If fewer than 20 candles are available after aggregation, returns a structured warning instead. Example: 'Is BTC-CLP RSI overbought on the 4-hour chart?'

Inputs: market_id (required), period, limit.

get_tickerA

Returns the current market snapshot for a Buda.com market: last traded price, best bid, best ask, 24h volume, and price change over 24h and 7d. All prices are floats in the quote currency (e.g. CLP for BTC-CLP). price_variation_24h is a decimal fraction (0.012 = +1.2%). Example: 'What is the current Bitcoin price in Chilean pesos?'

Inputs: market_id (required).

get_tradesA

Returns recent trade history for a Buda.com market as typed objects. Each entry has timestamp_ms (integer), amount (float, base currency), price (float, quote currency), and direction ('buy' or 'sell'). Example: 'What was the last executed price for BTC-CLP and was it a buy or sell?'

Inputs: market_id (required), limit, timestamp.

simulate_orderA

[DEPRECATED: prefer get_real_quotation for server-side accurate quotes] Simulates a buy or sell order on Buda.com using live ticker data — no order is placed. Returns estimated fill price, fee, total cost, and slippage vs mid-price. Omit 'price' for a market order simulation; supply 'price' for a limit order simulation. All outputs are labelled simulation: true — this tool never places a real order. Example: 'How much would it cost to buy 0.01 BTC on BTC-CLP right now?'

Inputs: market_id (required), side (required), amount (required), price.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 17 tools

    Disambiguation4/5

    Most tools have clearly distinct purposes (trades, volume, spread, summary, indicators, etc.), but specify_market functions like get_ticker, get_market_summary, and get_market_volume have overlapping market snapshot data. However, descriptions differentiate them well (summary is one-call, volume focuses on volume, ticker is a snapshot).

    Naming Consistency4/5

    Tools follow a consistent verb_noun pattern with 'get_' prefix, e.g., get_trades, get_spread, get_markets. Minor deviations include calculate_position_size, simulate_order, and compare_markets, which use different verbs but are still readable and fit the domain.

    Tool Count4/5

    17 tools is slightly above the ideal 3-15 but still well-scoped for a comprehensive market data server. Each tool serves a specific market data or analysis function, and there are no redundant tools (though simulate_order is deprecated, it is still useful for backward compatibility).

    Completeness4/5

    The tool surface covers a broad range of market data needs: market overview, order book, trades, history, technical indicators, sentiment, quotation, and stablecoin liquidity. Minor gaps include lack of direct order placement (but that is out of scope for a read-only server) and no explicit tool for order book depth beyond get_orderbook, but the main analytics are well covered.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Provides real-time and historical cryptocurrency market data from 100+ exchanges including prices, OHLCV data, market statistics, and order books through the CCXT library with intelligent caching.
      -
    • -
      license
      Not graded
      quality
      Not graded
      maintenance
      Real-time financial market data MCP server. Stocks, crypto, technicals, sentiment, FDA calendar. No API keys required.
      -
    • A
      license
      A
      quality
      D
      maintenance
      Live market data for AI agents. 8 tools: real-time crypto prices, OHLCV candles, order books, market cap rankings, trending coins, technical analysis (RSI/SMA/z-score), asset comparison, and Fear & Greed index. Zero API keys, zero dependencies.
      2
      8
      1
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Real-time institutional crypto & equity orderflow intelligence. Detects BUY/SELL pressure from live Binance L2 orderbook and aggressive trade feeds for any USDT pair or US equity.
      10
      34 PyPI
      5
      MIT