buda-mcp — Buda.com Cryptocurrency Exchange

buda-mcp

Buda.com 向けの MCP サーバーです。チリ、コロンビア、ペルーを代表する暗号資産取引所です。MCP 対応のあらゆる AI アシスタントから、市場データ、オーダーブック、取引履歴、スプレッド、テクニカル指標、価格シミュレーションにリアルタイムでアクセスできます。アカウントも API キーも必要ありません。

---

クイックスタート

npx @guiie/buda-mcp

または、恒久的にインストールします。

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

---

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

---

ツール

すべてのツールは公開されており、API キーやアカウントは必要ありません。

get_market_summary ⭐ まずはこちら

1 回の呼び出しで、最終価格、買い気配／売り気配、スプレッド率、24 時間の取引量、価格変動、liquidity_rating（high／medium／low）をまとめて取得します。特定の市場について質問されたときに、最初に使うのに最適なツールです。

パラメーター	型	必須	説明
market_id	string	はい	市場 ID（例：BTC-CLP）。

---

get_markets

Buda.com のすべての取引ペアを一覧表示するか、特定の市場の詳細（手数料、最小注文サイズ、割引ティア）を取得します。

パラメーター	型	必須	説明
market_id	string	いいえ	市場 ID（例：BTC-CLP）。すべての市場を一覧表示するには省略します。

---

get_ticker

現在のスナップショットを取得します。最終価格、最良買い気配／売り気配、24 時間の取引量、過去 24 時間および 7 日間の価格変動を確認できます。

パラメーター	型	必須	説明
market_id	string	はい	市場 ID（例：BTC-CLP、ETH-COP）。

---

get_orderbook

現在のオーダーブックを取得します。買い注文と売り注文を、{price, amount} オブジェクトとしてソートして返します。

パラメーター	型	必須	説明
market_id	string	はい	市場 ID。
limit	number	いいえ	片側あたりの最大価格レベル数（デフォルト：すべて）。

---

get_trades

最近の取引履歴を、型付きオブジェクト（{timestamp_ms, amount, price, direction}）として取得します。

パラメーター	型	必須	説明
market_id	string	はい	市場 ID。
limit	number	いいえ	取引件数（デフォルト 50、最大 100）。
timestamp	number	いいえ	Unix 秒。この時刻より前の取引を返します（ページネーション）。

---

get_market_volume

売買別（bid = 買い、ask = 売り）の過去 24 時間および 7 日間の取引量を取得します。

パラメーター	型	必須	説明
market_id	string	はい	市場 ID。

---

get_spread

買い気配／売り気配のスプレッドを取得します。売り気配価格に対する絶対値と割合を返します。

パラメーター	型	必須	説明
market_id	string	はい	市場 ID。

---

compare_markets

指定したベース通貨について、すべてのクオート通貨とのペアのティッカーデータを並べて比較します。

パラメーター	型	必須	説明
base_currency	string	はい	ベース通貨（例：BTC、ETH）。

---

get_price_history

生の取引履歴から集計した OHLCV ローソク足を取得します（Buda にはネイティブのローソク足エンドポイントがありません）。5m、15m、30m、1h、4h、1d の期間に対応しています。

パラメーター	型	必須	説明
market_id	string	はい	市場 ID。
period	string	いいえ	5m／15m／30m／1h／4h／1d（デフォルト 1h）。
limit	number	いいえ	集計前に取得する生の取引件数（デフォルト 100、最大 1000）。

---

get_arbitrage_opportunities

Buda の CLP、COP、PEN 市場における資産の国間価格差を、USDC に換算して検出します。

パラメーター	型	必須	説明
base_currency	string	はい	例：BTC。
threshold_pct	number	いいえ	報告する最小価格差（デフォルトは 0.5）。

---

simulate_order

リアルタイムのティッカーデータを使って買い注文または売り注文をシミュレーションします。実際に注文が発注されることはありません。estimated_fill_price、fee_amount、total_cost、slippage_vs_mid_pct を返します。すべての応答には simulation: true が含まれます。

パラメーター	型	必須	説明
market_id	string	はい	マーケット ID。
side	buy | sell	はい	注文方向。
amount	number	はい	ベース通貨での注文数量。
price	number	いいえ	成行注文のシミュレーションでは省略します。

---

calculate_position_size

資金、リスク率、エントリー価格、損切り価格から、ケリー基準方式でポジションサイズを算出します。完全にクライアント側で処理され、API 呼び出しはありません。

パラメーター	型	必須	説明
market_id	string	はい	マーケット ID（コンテキスト用）。
capital	number	はい	算出の基準となる総資金。
risk_pct	number	はい	リスクにさらす資金の割合（0.1～10）。
entry_price	number	はい	エントリー価格。
stop_loss_price	number	はい	損切り価格。

---

get_market_sentiment

3 つの要素から総合センチメントスコア（−100～+100）を算出します。24 時間の価格変動（40％）、7 日平均に対する出来高（35％）、市場タイプの基準値に対するスプレッド（25％）が要素となります。score、label、component_breakdown、disclaimer を返します。

パラメーター	型	必須	説明
market_id	string	はい	マーケット ID。

---

get_technical_indicators

RSI（14）、MACD（12/26/9）、ボリンジャーバンド（20、2σ）、SMA 20、SMA 50 を、Buda の取引履歴からサーバー側で計算します（外部ライブラリは使用しません）。シグナルの解釈を返し、ローソク足が 20 本未満の場合は構造化された警告を返します。disclaimer も含まれます。

パラメーター	型	必須	説明
market_id	string	はい	マーケット ID。
period	string	いいえ	1h / 4h / 1d（デフォルトは 1h）。
limit	number	いいえ	取得する生の取引データ数（500～1000）。

---

get_real_quotation

注文を発注せずに、指定された注文数量と方向に応じたリアルタイムの見積もりを返します。正確な約定価格、手数料、残高の変動を確認できます。

パラメーター	型	必須	説明
market_id	string	はい	マーケット ID。
type	Bid | Ask	はい	注文方向。
amount	number	はい	ベース通貨での注文数量。
limit_price	number	いいえ	指値見積もりの指値価格。

---

get_available_banks

指定した通貨の国で、法定通貨の入出金に利用できる銀行の一覧を返します。

パラメーター	型	必須	説明
currency	string	はい	法定通貨コード（例：CLP、COP、PEN）。

---

MCP リソース

ツールに加えて、サーバーはクライアントが直接読み取れる MCP リソースを公開しています。

URI	説明
buda://markets	Buda.com の全市場を含む JSON リスト
buda://ticker/{market}	特定市場の JSON ティッカー（例：buda://ticker/BTC-CLP）
buda://summary/{market}	流動性評価を含む市場の完全な概要（例：buda://summary/BTC-CLP）

---

対応市場

クォート通貨	国	ペアの例
CLP	チリ	BTC-CLP、ETH-CLP、SOL-CLP
COP	コロンビア	BTC-COP、ETH-COP、SOL-COP
PEN	ペルー	BTC-PEN、ETH-PEN
USDC	米ドル連動	BTC-USDC、USDT-USDC
BTC	クロス	ETH-BTC、LTC-BTC、BCH-BTC

---

ソースからビルド

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)

テストを実行します：

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 デプロイ

dist/http.js エントリーポイントは、次のエンドポイントを備えた Express サーバーを起動します。

• POST /mcp — Streamable HTTP MCP トランスポート
• GET /mcp — SSE ストリーミングトランスポート
• GET /health — ヘルスチェック（{ status }）
• GET /.well-known/mcp/server-card.json — Smithery 互換の静的ツールマニフェスト

環境変数

変数	必須	説明
PORT	いいえ	HTTP のリッスンポート（デフォルト：3000）
MCP_RATE_LIMIT	いいえ	/mcp における IP ごとの 1 分あたりの最大リクエスト数（デフォルト：120）
TRUST_PROXY_HOPS	いいえ	X-Forwarded-For の信頼対象とするリバースプロキシのホップ数（デフォルト：1）。

---

セキュリティ

サーバーが公開するのは Buda.com の公開 API エンドポイントのみです。認証情報は受け付けず、保存もしません。プロンプトインジェクションを防ぐため、すべてのツールパラメーターに入力検証を適用します。エラーメッセージはサニタイズされます。内部の詳細情報（パス、上流のエラー）は stderr にのみ記録され、呼び出し元に返されることはありません。

脆弱性の報告

セキュリティ上の問題は、公開 issue ではなく、GitHub Security Advisories から非公開で報告してください。開示ポリシーの全文は SECURITY.md をご覧ください。

---

プロジェクト構成

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

---

ドキュメント

エージェントのコンテキスト：AGENTS.md | 運用メモ：docs/PROJECT_MEMORY.md | 変更履歴：CHANGELOG.md | セキュリティ：SECURITY.md

---

ライセンス

MIT — Buda.com API ドキュメント