alpaka-mcp

<p align="center"> <img src="https://raw.githubusercontent.com/vikrambtech2025-png/alpaka-mcp/main/assets/banner.png" alt="alpaka-mcp banner" width="100%" /> </p>

<h1 align="center">🦙 alpaka-mcp</h1>

<p align="center"> <strong>Trade US stocks, ETFs, and crypto through AI assistants and the terminal</strong> </p>

<p align="center"> <a href="https://github.com/vikrambtech2025-png/alpaka-mcp/actions"><img src="https://github.com/vikrambtech2025-png/alpaka-mcp/workflows/CI/badge.svg" alt="CI"></a> <a href="https://github.com/vikrambtech2025-png/alpaka-mcp/blob/main/LICENSE"><img src="https://img.shields.io/github/license/vikrambtech2025-png/alpaka-mcp" alt="License"></a> <img src="https://img.shields.io/badge/python-3.11+-blue" alt="Python 3.11+"> <img src="https://img.shields.io/badge/mcp-server-brightgreen" alt="MCP Server"> <a href="https://alpaca.markets"><img src="https://img.shields.io/badge/alpaca-py-0.30+-orange" alt="alpaca-py"></a> </p>

<p align="center"> 16 MCP tools • 12 CLI commands • Rate limiting • Retry • Structured logging • Live trading guard </p>

---

What is this?

alpaka-mcp is a production-ready MCP server + CLI that connects AI assistants (Claude Desktop, Cursor, VS Code Copilot) and your terminal directly to the Alpaca Trading API. Trade stocks, ETFs, and crypto with natural language — or from the command line.

Built on alpaca-py and the MCP Python SDK.

Defaults to paper trading — real market data, simulated funds, zero real money at risk.

---

Quick Start

1. Get Alpaca API Keys (free)

Sign up at alpaca.markets → Paper Trading → API Keys

2. Install

git clone https://github.com/vikrambtech2025-png/alpaka-mcp.git
cd alpaka-mcp
uv sync

3. Configure

cp .env.example .env
# Add your API keys to .env

4. Run

uv run alpaka-mcp          # MCP server (stdio for Claude/Cursor)
uv run alpaka account      # CLI — check account
uv run mcp dev src/alpaka_mcp/server.py  # MCP Inspector

---

Connect to AI Assistants

<details> <summary><strong>Claude Desktop</strong></summary>

Add to %AppData%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "alpaka": {
      "command": "uv",
      "args": ["--directory", "C:\\path\\to\\alpaka-mcp", "run", "alpaka-mcp"],
      "env": {
        "ALPACA_API_KEY": "your_key",
        "ALPACA_SECRET_KEY": "your_secret",
        "ALPACA_PAPER": "true"
      }
    }
  }
}

</details>

<details> <summary><strong>Cursor</strong></summary>

Add to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "alpaka": {
      "command": "uv",
      "args": ["--directory", "/path/to/alpaka-mcp", "run", "alpaka-mcp"],
      "env": {
        "ALPACA_API_KEY": "your_key",
        "ALPACA_SECRET_KEY": "your_secret",
        "ALPACA_PAPER": "true"
      }
    }
  }
}

</details>

<details> <summary><strong>VS Code</strong></summary>

Add to .vscode/mcp.json:

{
  "servers": {
    "alpaka": {
      "command": "uv",
      "args": ["--directory", "/path/to/alpaka-mcp", "run", "alpaka-mcp"],
      "env": {
        "ALPACA_API_KEY": "your_key",
        "ALPACA_SECRET_KEY": "your_secret",
        "ALPACA_PAPER": "true"
      }
    }
  }
}

</details>

---

MCP Tools (16)

<table> <tr><th>Account</th><th>Trading</th><th>Positions</th></tr> <tr> <td valign="top">

Tool	Description
get_account	Balance, equity, buying power, day trades
get_portfolio	All open positions with P&L

</td> <td valign="top">

Tool	Description
buy	Place buy order (market/limit/stop/stop-limit)
sell	Place sell order (market/limit)
get_orders	List orders by status and symbols
cancel_order	Cancel a specific order
cancel_all_orders	Cancel all open orders

</td> <td valign="top">

Tool	Description
get_position	Single position details
close_position	Liquidate (full or partial)

</td> </tr> </table>

<table> <tr><th>Stock Data</th><th>Crypto Data</th><th>Discovery</th></tr> <tr> <td valign="top">

Tool	Description
get_stock_quote	Latest bid/ask quote
get_stock_bars	Historical OHLCV bars
get_stock_snapshot	Full snapshot (trade, quote, daily, 1-min)

</td> <td valign="top">

Tool	Description
get_crypto_quote	Latest crypto bid/ask
get_crypto_bars	Historical crypto OHLCV bars

</td> <td valign="top">

Tool	Description
search_assets	Search stocks/ETFs/crypto by name or symbol
get_market_clock	Market open/close status

</td> </tr> </table>

---

CLI Commands (12)

alpaka account                    # Account balance & buying power
alpaka portfolio                  # Open positions with color-coded P&L
alpaka quote AAPL                 # Bid/ask quote (stocks or crypto)
alpaka buy AAPL --qty 10          # Buy 10 shares
alpaka buy BTC/USD -n 500         # Buy $500 of Bitcoin
alpaka sell AAPL --qty 5          # Sell 5 shares
alpaka orders                     # List open orders
alpaka orders --status closed     # List filled orders
alpaka cancel <order-id>          # Cancel specific order
alpaka cancel-all                 # Cancel everything open
alpaka bars AAPL --tf 1Day        # Historical bars
alpaka clock                      # Is the market open?
alpaka search apple               # Find tradeable assets

All commands support --json for machine-readable output:

$ uv run alpaka account --json
{
  "status": "ACTIVE",
  "equity": "100000.00",
  "buying_power": "200000.00",
  "cash": "100000.00",
  "portfolio_value": "100000.00",
  "daytrade_count": 0,
  "pattern_day_trader": false,
  "mode": "paper"
}

---

Production Features

Feature	How It Works
Resilient Client	Transparent proxy wraps every API call with rate limiting + retry
Rate Limiting	3 independent token buckets (200 req/min each) — trading, stock data, crypto
Retry + Backoff	3 attempts with 1s/2s/4s exponential backoff on 429, 500, connection errors
Non-Blocking Async	MCP tools use asyncio.to_thread() — event loop never blocks
Structured Logging	JSON audit trail: logs/trades.jsonl + logs/errors.jsonl
Input Validation	Symbols, quantities, prices, order types validated before API calls
Live Trading Guard	Requires ALPACA_LIVE_CONFIRM=true + 5s countdown for real money
Config Validation	Rejects placeholder API keys with clear setup instructions
Thread Safety	lru_cache client initialization, no mutable global state
CLI Error Handling	Every command wrapped — clean errors, no tracebacks

---

Architecture

src/alpaka_mcp/
├── server.py          # MCP server entry point (stdio)
├── cli.py             # 12 Typer commands + JSON output
├── config.py          # pydantic-settings + credential validation
├── clients.py         # ResilientClient proxy (rate limit + retry + async)
├── utils.py           # Response formatting
├── logging.py         # Structured JSON logging
├── rate_limiter.py    # Token bucket rate limiters (sync + async)
├── retry.py           # Exponential backoff (sync + async)
├── validation.py      # Input validation
└── tools/             # 16 MCP tools
    ├── account.py     # get_account, get_portfolio
    ├── trading.py     # buy, sell, get_orders, cancel_order, cancel_all
    ├── positions.py   # get_position, close_position
    ├── stock_data.py  # get_stock_quote, get_stock_bars, get_stock_snapshot
    ├── crypto_data.py # get_crypto_quote, get_crypto_bars
    └── discovery.py   # search_assets, get_market_clock

---

Docker

# MCP server
docker compose up alpaka-mcp

# CLI via docker
docker compose run --rm alpaka-cli account
docker compose run --rm alpaka-cli portfolio

Logs persist in a Docker volume at /app/logs.

---

Environment Variables

Variable	Default	Description
ALPACA_API_KEY	(required)	Your Alpaca API key
ALPACA_SECRET_KEY	(required)	Your Alpaca secret key
ALPACA_PAPER	true	Paper trading mode
ALPACA_LIVE_CONFIRM	false	Must be true for live trading
ALPACA_LOG_DIR	logs	Log file directory
ALPACA_LOG_LEVEL	INFO	Logging verbosity

---

Testing

# Unit tests (no API keys needed)
uv run pytest tests/ --ignore=tests/test_integration.py -v

# Integration tests (needs real paper API keys)
ALPACA_API_KEY=pk_xxx ALPACA_SECRET_KEY=sk_xxx uv run pytest tests/test_integration.py -v

---

Safety

• Paper trading by default — real money requires explicit opt-in
• Live trading requires both ALPACA_PAPER=false AND ALPACA_LIVE_CONFIRM=true
• 5-second countdown on live trading startup
• All errors formatted cleanly — no tracebacks sent to LLMs
• Rate limiting prevents accidental API abuse
• Structured audit trail for every trade

---

License

MIT

---

<p align="center"> Built with care by <a href="https://github.com/vikrambtech2025-png">Vikram</a> </p>