Alpaca MCP server setup
Figures on this page are as of 2026-09. Fees, limits and margin tiers change — check the venue's own docs before acting on a number.
Alpaca is the exception among trading venues: it publishes its own MCP server
(alpacahq/alpaca-mcp-server) rather than leaving it to the community. For the
major crypto exchanges and for Interactive Brokers, what exists is third-party
code.
That changes the trust question, and it shows in the defaults.
The three environment variables
The entire configuration surface that matters:
| Variable | Required | Default |
|---|---|---|
ALPACA_API_KEY | Yes | — |
ALPACA_SECRET_KEY | Yes | — |
ALPACA_PAPER_TRADE | No | true |
ALPACA_PAPER_TRADE defaulting to true is the detail worth noticing. Out
of the box, an incorrectly configured install trades fake money. Going live is
an explicit act: set it to false, supply live credentials, restart the client.
This is the right way round and it is not universal. Plenty of software defaults to production and relies on you to know better.
Installation
The server runs as uvx alpaca-mcp-server (or the Docker equivalent) across
clients — Claude Desktop, Cursor, VS Code, PyCharm, Claude Code, Antigravity
CLI. The mechanics differ only in which config file holds the entry:
| Client | Config |
|---|---|
| Claude Desktop | ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows) |
| Cursor | ~/.cursor/mcp.json, or the Cursor Directory |
| VS Code | .vscode/mcp.json in the project root |
| PyCharm | Settings → Tools → Model Context Protocol |
| Claude Code | claude mcp add |
Check the repository for current syntax before copying anything — this is third-party-hosted configuration that changes, and the version you install is the one that matters.
Restrict the tool set — this is the part people skip
ALPACA_TOOLSETS takes a comma-separated list and limits which tools the server
exposes. When unset, all toolsets are enabled.
| Toolset | Covers |
|---|---|
account | Account info, portfolio history, activities |
trading | Orders, positions, option exercise |
watchlists | Watchlist CRUD |
assets | Asset lookup, contracts, market calendar |
stock-data | Bars, quotes, trades, snapshots, screeners |
crypto-data | Bars, quotes, trades, snapshots, orderbooks |
options-data | Bars, quotes, trades, chain, Greeks |
corporate-actions | Action announcements |
news | News articles |
fixed-income-data | Bond and treasury quotes |
locates | Short-sale locate requests |
trading is the one that places orders. Omitting it gives you a capable
read-and-analyse setup with no order path at all — which, for a large share of
what people actually want from this, is enough.
A sensible starting point is everything except trading. Server-side filtering
is worth more than hoping the model does not call something, because it removes
the tool rather than discouraging its use.
What Alpaca says about the risk
Worth quoting rather than paraphrasing, because a vendor saying this about its own product is unusual:
“This server can place real trades and access your portfolio. Treat your API keys as sensitive credentials. Review all actions proposed by the LLM carefully, especially for complex options strategies or multi-leg trades.”
And on exposure:
“This package does not configure remote MCP authentication, so do not expose it directly to the public internet with your Alpaca API keys.”
That second one matters because Claude Mobile and ChatGPT need remote MCP servers, so the obvious way to use this from a phone is to put it somewhere reachable. The documentation says explicitly not to do that with this package as shipped. There is no authentication in front of it.
On options specifically: “Options trading is not suitable for all investors due to its inherent high risk, which can potentially result in significant losses.”
Two things that will catch you
V2 is not V1. The current version is a complete rewrite on FastMCP and OpenAPI, and the documentation is blunt: “None of the V1 tools exist in V2.” Tool names, parameters and configuration all changed. Any tutorial, prompt or script written against V1 is invalid. Pin a version and read the upgrade notes rather than tracking latest.
Data freshness has a plan attached. Access to the latest 15 minutes of market data requires a subscription to the Algo Trader Plus Plan. Without it the model is reasoning on delayed data — and, more to the point, it has no way to know that. Delayed data looks exactly like current data.
That second point generalises beyond Alpaca: a model cannot tell that its inputs are stale. If your data is delayed, the staleness has to be handled by you, not noticed by it.
Paper and live are the same API
Paper is https://paper-api.alpaca.markets, live is
https://api.alpaca.markets, both under /v2, both authenticated with
APCA-API-KEY-ID and APCA-API-SECRET-KEY. The specification is identical —
which is what makes ALPACA_PAPER_TRADE a clean switch, and also what makes
pointing at the wrong one so easy. Alpaca’s own docs warn about connecting to
the right domain for exactly this reason.
Credentials differ per environment, and the secret key is shown once at generation and cannot be retrieved afterwards.
A sensible progression
ALPACA_PAPER_TRADE=true(the default), all toolsets. Learn what the model does with them.- Paper, deliberately try to get a bad order through. Find out what stops you.
- Live,
ALPACA_TOOLSETSwithouttrading. Real data, no order path. - Live with
trading, small size, every order reviewed.
Step 3 is where most of the value is, and a lot of people would be content staying there.
FAQ
Does the Alpaca MCP server default to paper trading?
Yes. ALPACA_PAPER_TRADE is optional and defaults to true, so a fresh install
trades paper unless you deliberately set it to false and supply live
credentials. Going live requires updating the env block in your client config
and restarting.
How do I stop the model from placing orders at all?
Set ALPACA_TOOLSETS to a list that excludes trading. That toolset covers
orders, positions and option exercise; without it the order tools are not
exposed to the model at all. This is stronger than instructing the model not to
trade, because there is nothing to call. Pair it with an API key that lacks
trade permission and neither layer is load-bearing alone.
Can I run this on a server so I can use it from my phone?
Not as shipped. The documentation states the package “does not configure remote MCP authentication” and says not to expose it directly to the public internet with your Alpaca API keys. Claude Mobile and ChatGPT require remote MCP servers, so the phone use case needs authentication you would have to add yourself.
I upgraded and my prompts stopped working.
Expected. V2 is a complete rewrite and none of the V1 tools exist in it — names, parameters and configuration all changed. Read the upgrade guide, and pin a version so this happens when you choose rather than when the package updates.