Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Finance

alpaca-trading-paper-trading-mcp

Preview, submit, inspect, and manage Alpaca paper-trading orders using the Alpaca Trading API MCP Server. Supports US equities, options, and crypto. Use this skill when you want your AI agent to execute paper trades through MCP tool calls — no CLI installation or direct API coding required.

alpacahq · AI review on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add alpacahq/alpaca-skills --skill alpaca-trading-paper-trading-mcp

About this skill


name: alpaca-trading-paper-trading-mcp description: > Preview, submit, inspect, and manage Alpaca paper-trading orders using the Alpaca Trading API MCP Server. Supports US equities, options, and crypto. Use this skill when you want your AI agent to execute paper trades through MCP tool calls — no CLI installation or direct API coding required.

Alpaca Paper Trading — MCP Server Version

Use this skill when you want your AI agent to preview, submit, inspect, and manage paper-trading orders using the Alpaca Trading API MCP Server.

This skill is written for you, a Trading API user working with your own Alpaca paper-trading account. Your agent calls MCP tools directly — no CLI installation or raw HTTP requests needed. The MCP server handles authentication and API communication.

This is the MCP-server-specific version. A generic (implementation-agnostic) version and a CLI version are also available as companion skills.


0 — How your AI agent should use this skill

  1. Start with the signal source. Whether it originates from a backtest result, a manual trading idea, a scheduled trigger, or a conversational request — identify what is driving the trade.
  2. Reiterate strategy logic and confirm with you. Your agent must restate the trading idea in its own words and wait for your confirmation before proceeding.
  3. Gather and confirm ALL configurations. Timing, asset class, symbol, side, quantity or notional amount, order type, time-in-force, limit/stop prices, extended-hours flag, risk controls (position limits, max order size, loss thresholds), and margin intent.
  4. Discover available MCP tools. Your agent must call GetDynamicTools to find the Alpaca MCP namespace and inspect available tool schemas before calling any tool. Tool names and parameters vary by MCP server implementation — never assume.
  5. Verify paper environment. Read env.ALPACA_PAPER_TRADE from the host's MCP config file — no tool exposes it — and require it to be absent, true, 1, or yes. Then confirm the account is active and unblocked. If paper mode cannot be proven, STOP immediately and tell you.
  6. Show a complete order preview table. Every parameter that will be sent to the order-placement tool must be visible to you before submission.
  7. Ask whether you want explicit confirmation before each order (default: ON). Respect your preference for the rest of the session.
  8. Submit via the order-placement tool for the asset class. Placement is split across stock, crypto, and option tools — select by asset class, then pass the confirmed parameters exactly as previewed.
  9. Monitor with the order lookup and order list tools. Report fills, rejections, partial fills, and portfolio impact.
  10. Never place live trades. Verify paper environment before every submission.

1 — Prerequisites

Required

  • Alpaca Trading API MCP Server installed and configured in your agent host (Cursor, etc.)
  • Paper trading API key and secret configured as environment variables in the MCP server configuration — never pasted into chat or passed as tool arguments
  • MCP server namespace discoverable via GetDynamicTools
  • Paper trading account active at Alpaca

Conditional

  • Options trading: must be enabled on your Alpaca paper account
  • Crypto trading: must be enabled on your Alpaca paper account

MCP Server Setup (Cursor)

The server is Alpaca's official MCP server, maintained at alpacahq/alpaca-mcp-server. That repository's README is the source of truth for the package name, command, and environment variables. The configuration below reflects v2.

Add it to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "alpaca-paper-trading": {
      "command": "uvx",
      "args": ["alpaca-mcp-server"],
      "env": {
        "ALPACA_API_KEY": "your-paper-key",
        "ALPACA_SECRET_KEY": "your-paper-secret",
        "ALPACA_PAPER_TRADE": "true"
      }
    }
  }
}
VariableRequiredDefaultPurpose
ALPACA_API_KEYYes—Paper API key
ALPACA_SECRET_KEYYes—Paper secret key
ALPACA_PAPER_TRADENotruePaper/live switch; false selects live. This skill requires true.
ALPACA_TOOLSETSNoallComma-separated toolsets to expose. Leaving it unset means you have all capabilities. Set it (for example account,trading,assets) only to narrow what the agent can reach.

Paper versus live is determined solely by ALPACA_PAPER_TRADE. The server derives the API host from that flag, so there is no base-URL variable to set and none to verify.

Verifying the MCP server is available

Your agent should run:

GetDynamicTools with pattern "alpaca"

If the namespace is not found, appears in "error" or "loading" state, or has namespaceStatus: "needsAuth":

  1. If "needsAuth" — authenticate via mcp_auth for that namespace, then retry.
  2. If "error" or not found — tell you to check the MCP server configuration in Cursor settings.
  3. Do not fall back to direct HTTP calls or CLI commands. This is the MCP version.

2 — Gather inputs

Input table

ParameterRequiredDefaultNotes
symbolYes—Ticker symbol (e.g., AAPL, BTC/USD, AAPL251219C00250000)
sideYes—buy or sell
qtyOne of qty/notional—Number of shares/units. Whole or fractional. Mutually exclusive with notional
notionalOne of qty/notional—Dollar amount. Stocks: market orders with day TIF only. Crypto: market orders only. Not available on place_option_order
typeNomarketStocks: market, limit, stop, stop_limit, trailing_stop. Crypto: market, limit, stop_limit. Options: market, limit. The parameter is type, not order_type
time_in_forceNoday (stocks), gtc (crypto), day (options)Stocks: day, `g
Read the complete source ↗