MCP 服务器

alpaka-mcp

MCP server and CLI for trading stocks, ETFs, and crypto via Alpaca, enabling natural language trading through AI assistants and terminal with paper trading defaults.

README

<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"> 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)

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>

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>

alpaka-mcp

README

What is this?

Quick Start

1. Get Alpaca API Keys (free)

2. Install

3. Configure

4. Run

Connect to AI Assistants

MCP Tools (16)

CLI Commands (12)

Production Features

Architecture

Docker

Environment Variables

Testing

Safety

License

推荐服务器