阿尔帕卡MCP服务器

Prerequisites

• Python 3.10+ (installation guide)
• uv (installation guide)
• Alpaca Trading API keys (free paper trading account)
• MCP client (Claude Desktop, Cursor, VS Code, etc.)

Integration tests (requires paper API keys)

ALPACA_API_KEY=... ALPACA_SECRET_KEY=... pytest tests/ -m integration -v ```

Setup

Add the server to your MCP client config, then restart the client. No init command, no .env files — credentials are set in one place only.

How to avoid V1-style usage in V2

MCP clients discover tools dynamically from the server. There is no config file where you "whitelist" tool names — the client gets whatever tools the server exposes. To avoid your client or AI assistant using V2 incorrectly:

1. Do not reuse V1 config — Treat V2 as a new server. Update your MCP client config with the new command/args; remove any .env or init-based setup.
2. Clear tool caches — Restart your MCP client (Claude Desktop, Cursor, VS Code, etc.) after switching so it fetches the new tool list instead of using a stale one.
3. Start a fresh chat/session — Existing conversations may have cached references to old tool names. Start a new chat so the LLM sees the current V2 tools and their schemas.
4. Update custom instructions and rules — If you have Cursor rules, Claude instructions, or other prompts that mention specific V1 tool names (e.g. "use get_account_info"), update them to match V2 tool names or remove those references and let the LLM discover tools from context.
5. Restrict tools with ALPACA_TOOLSETS — If you previously limited which capabilities your assistant could use, V2 supports server-side filtering via the ALPACA_TOOLSETS env var. See Configuration > Toolset Filtering for the list of toolsets.

Example Prompts

Basic Trading

1. What's my current account balance and buying power on Alpaca?
2. Show me my current positions in my Alpaca account.
3. Buy 5 shares of AAPL at market price.
4. Sell 5 shares of TSLA with a limit price of $300.
5. Cancel all open stock orders.
6. Cancel the order with ID abc123.
7. Liquidate my entire position in GOOGL.
8. Close 10% of my position in NVDA.
9. Place a limit order to buy 100 shares of MSFT at $450.
10. Place a market order to sell 25 shares of META.

Crypto Trading

1. Place a market order to buy 0.01 ETH/USD.
2. Place a limit order to sell 0.01 BTC/USD at $110,000.

Option Trading

1. Show me available option contracts for AAPL expiring next month.
2. Get the latest quote for the AAPL250613C00200000 option.
3. Retrieve the option snapshot for the SPY250627P00400000 option.
4. Liquidate my position in 2 contracts of QQQ calls expiring next week.
5. Place a market order to buy 1 call option on AAPL expiring next Friday.
6. What are the option Greeks for the TSLA250620P00500000 option?
7. Find TSLA option contracts with strike prices within 5% of the current market price.
8. Get SPY call options expiring the week of June 16th, 2025, within 10% of market price.
9. Place a bull call spread using AAPL June 6th options: one with a 190.00 strike and the other with a 200.00 strike.
10. Exercise my NVDA call option contract NVDA250919C001680.

Market Information

To access the latest 15-minute data, you need to subscribe to the Algo Trader Plus Plan. 1. What are the market open and close times today? 2. Show me the market calendar for next week. 3. Show me recent cash dividends and stock splits for AAPL, MSFT, and GOOGL in the last 3 months. 4. Get all corporate actions for SPY including dividends, splits, and any mergers in the past year. 5. What are the upcoming corporate actions scheduled for SPY in the next 6 months?

Historical & Real-time Data

1. Show me AAPL's daily price history for the last 5 trading days.
2. What was the closing price of TSLA yesterday?
3. Get the latest bar for GOOGL.
4. What was the latest trade price for NVDA?
5. Show me the most recent quote for MSFT.
6. Retrieve the last 100 trades for AMD.
7. Show me 1-minute bars for AMZN from the last 2 hours.
8. Get 5-minute intraday bars for TSLA from last Tuesday through last Friday.
9. Get a comprehensive stock snapshot for AAPL showing latest quote, trade, minute bar, daily bar, and previous daily bar all in one view.
10. Compare market snapshots for TSLA, NVDA, and MSFT to analyze their current bid/ask spreads, latest trade prices, and daily performance.

Orders

1. Show me all my open and filled orders from this week.
2. What orders do I have for AAPL?
3. List all limit orders I placed in the past 3 days.
4. Filter all orders by status: filled.
5. Get me the order history for yesterday.

Watchlists

At this moment, you can only view and update trading watchlists created via Alpaca's Trading API through the API itself 1. Create a new watchlist called "Tech Stocks" with AAPL, MSFT, and NVDA. 2. Update my "Tech Stocks" watchlist to include TSLA and AMZN. 3. What stocks are in my "Dividend Picks" watchlist? 4. Remove META from my "Growth Portfolio" watchlist. 5. List all my existing watchlists.

Asset Information

1. Search for details about the asset 'AAPL'.
2. Show me the top 5 tradable crypto assets by trading volume.
3. Get all NASDAQ active US equity assets and filter the results to show only tradable securities

Combined Scenarios

1. Get today's market clock and show me my buying power before placing a limit buy order for TSLA at $340.
2. Place a bull call spread with SPY July 3rd options: sell one 5% above and buy one 3% below the current SPY price.

Configuration

All configuration is through environment variables set in your MCP client config. No files are written to disk.

Getting Your API Keys

1. Visit the Alpaca Dashboard
2. Create a free paper trading account
3. Generate API keys from the dashboard

If you had custom V1 workflows

If you documented allowed tools, wrote scripts that call tools by name, or built prompts around specific V1 tool/parameter shapes — treat them as obsolete. Recreate them using the Available Tools listed below and the current parameter schemas exposed by the server.

VS Code

Create .vscode/mcp.json in your project root. See the official docs.

{
  "mcp": {
    "servers": {
      "alpaca": {
        "type": "stdio",
        "command": "uvx",
        "args": ["alpaca-mcp-server"],
        "env": {
          "ALPACA_API_KEY": "your_alpaca_api_key",
          "ALPACA_SECRET_KEY": "your_alpaca_secret_key"
        }
      }
    }
  }
}

PyCharm

See the official guide.

1. Go to File → Settings → Tools → Model Context Protocol (MCP) 2. Add a new server: - Type: stdio - Command: uvx - Arguments: alpaca-mcp-server 3. Set environment variables:

   ALPACA_API_KEY=your_alpaca_api_key
   ALPACA_SECRET_KEY=your_alpaca_secret_key
  

Claude Code

claude mcp add alpaca --scope user --transport stdio uvx alpaca-mcp-server \
  --env ALPACA_API_KEY=your_alpaca_api_key \
  --env ALPACA_SECRET_KEY=your_alpaca_secret_key

Verify with /mcp in the Claude Code CLI.

Gemini CLI

See the Gemini CLI MCP docs.

Add to your settings.json:

{
  "mcpServers": {
    "alpaca": {
      "type": "stdio",
      "command": "uvx",
      "args": ["alpaca-mcp-server"],
      "env": {
        "ALPACA_API_KEY": "your_alpaca_api_key",
        "ALPACA_SECRET_KEY": "your_alpaca_secret_key"
      }
    }
  }
}

Docker

git clone https://github.com/alpacahq/alpaca-mcp-server.git
cd alpaca-mcp-server
docker build -t mcp/alpaca:latest .

Add to your MCP client config:

{
  "mcpServers": {
    "alpaca": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "ALPACA_API_KEY=your_key",
        "-e", "ALPACA_SECRET_KEY=your_secret",
        "-e", "ALPACA_PAPER_TRADE=true",
        "mcp/alpaca:latest"
      ]
    }
  }
}

Troubleshooting

• uv/uvx not found: Install uv from the official guide (https://docs.astral.sh/uv/getting-started/installation/) and then restart your terminal so uv/uvx are on PATH.
• Credentials missing: Set ALPACA_API_KEY and ALPACA_SECRET_KEY in the client's env block. Paper mode default is ALPACA_PAPER_TRADE = True.
• Client didn't pick up new config: Restart the client (Cursor, Claude Desktop, VS Code) after changes.
• HTTP port conflicts: If using --transport streamable-http, change --port to a free port.