alpaka-mcp

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

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

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

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

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

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

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

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

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

# MCP server
docker compose up alpaka-mcp

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

# 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