Alpaca MCP Server v2: a spec-derived trading bridge for LLM clients

The gap between an LLM and a brokerage account

A language model can describe a covered call but it cannot read your buying power or place the order. Closing that gap normally means writing glue code: an HTTP client, auth handling, order serialization, and a function schema for every endpoint you want the model to reach. Alpaca's MCP server removes that layer for Alpaca accounts specifically. It is a Model Context Protocol server, so an MCP-capable client such as Claude Desktop, Cursor or VS Code connects to it and discovers its tools at runtime. The README frames the target user as someone who wants to trade stocks, ETFs, crypto and options, run data analysis and build strategies in plain English from those clients. The audience is therefore narrower than "Python developers": you need an MCP client and an Alpaca account, and the free paper trading account is the documented starting point. If you already have a working Python SDK integration with your own tool schemas, this server replaces work you have already done rather than filling a gap.

Tools generated from OpenAPI specs, not hand-written

The v2 rewrite is built with FastMCP and OpenAPI. That choice explains most of the project's behaviour. Instead of hand-crafting each tool, the server derives its tool surface from Alpaca's API specifications, with overrides applied on top. The README's migration table puts it plainly: v1 tool names were hand-crafted, v2 names are spec-derived with overrides, and parameters are aligned with the Alpaca API specs rather than custom schemas. The practical consequence is coverage. New endpoints that appear in the specs can flow into the tool list without someone writing a wrapper by hand. The cost is stability. When the source specs change shape, the generated schemas can change with them, and the README warns that names may overlap between versions while schemas differ. MCP clients discover tools dynamically, so there is no local file listing which tools exist; the client receives whatever the server exposes at connection time. That dynamic discovery is also why the migration instructions insist on restarting the client and starting a fresh chat: an existing conversation may hold cached references to tool names that no longer resolve.

Configuration lives in the MCP client, not in a .env file

Setup is a JSON block in the client's config file. On macOS that is ~/Library/Application Support/Claude/claude_desktop_config.json; on Windows it is %APPDATA%\Claude\claude_desktop_config.json. The README's example registers a server named alpaca that runs uvx alpaca-mcp-server, with ALPACA_API_KEY and ALPACA_SECRET_KEY passed through the env object. Prerequisites are Python 3.10 or newer, uv, Alpaca API keys and an MCP client. The README states there is no init command and no .env file in v2, and that credentials are set in one place only. For anyone coming from v1, that is a real change: v1 used .env plus an init command, and the migration table lists configuration as one of the changed aspects. One documented limitation sits here. Alpaca does not provide a hosted remote MCP server, so using this on the Claude mobile app requires hosting it remotely on a cloud provider and adding it as a custom connector. The local stdio setup in the README does not cover that case.

ALPACA_TOOLSETS is the access control you actually have

Because the client discovers tools dynamically, there is no config file where you whitelist tool names. The README says this directly and points to ALPACA_TOOLSETS as the mechanism: an environment variable that filters which tools the server exposes, described as server-side filtering and as the way to restrict tools. This is the one lever that limits what an assistant can reach, and it is the closest thing the project offers to a permission model. It is not a per-order approval gate, a spend limit, or a read-only switch. If your concern is that a model might place an order during a data-analysis conversation, ALPACA_TOOLSETS is the documented control, and the README refers to the Configuration section for the list of toolsets rather than enumerating them inline. The README also gives upgrade advice for people who previously limited capabilities in v1: recreate that restriction with ALPACA_TOOLSETS. Treat the exact toolset names as something to read in the repository, not something to guess from this description.

The v1 to v2 break is deliberate and total

The README states that none of the v1 tools exist in v2, and that v2 cannot be used as a drop-in replacement if your setup depends on specific v1 tool names or parameters. It also says to assume no backward compatibility. That is unusual candour for a project's own upgrade guide, and it is the single most important operational fact here. Anything built around v1 shapes is obsolete: documented allowed-tool lists, scripts that call tools by name, and prompts written against v1 parameter schemas. The README's remediation steps are specific. Do not reuse v1 config; update the client config with the new command and args and remove .env or init-based setup. Restart the client so it fetches the new tool list instead of a stale one. Start a new chat so the model sees current schemas. Update Cursor rules or Claude instructions that reference v1 tool names. If you cannot do that work now, the documented escape hatch is to pin the last v1 release, for example uvx alpaca-mcp-server==1.x.x serve, since v1 remains on PyPI. That is a maintenance decision, not a permanent answer, because a pinned v1 will not receive v2-era changes.

Where this is the wrong tool

This server is a thin, spec-derived bridge, and that shape has limits. It is not a strategy engine. The README's positioning mentions building strategies in plain English, but the mechanism described is tool exposure, not backtesting, portfolio construction or risk logic; those remain the model's job and your responsibility. It is also not a hosted service. The absence of a remote MCP server means mobile use requires you to run the server on a cloud provider yourself, which shifts the operational burden onto you. Credentials are passed as environment variables in the client config, so their security is your client's security model, not something the server adds. And if you need deterministic, auditable order placement, a generated tool schema is a weaker foundation than a hand-written call with explicit parameters and your own logging. The project is also young in version terms: the README describes v2 as a complete rewrite, and the repository lists no releases, so the material gives no version history to reason about. If your workflow depends on a stable tool contract, that contract is currently defined by upstream specs rather than by this project's own semver.

The alternative: the Alpaca Python SDK

The obvious comparison is the Alpaca Python SDK, which the README links from its badge row. The difference is where the interface is defined. With the SDK you write Python that calls Alpaca's API and you decide what your program is allowed to do; the model, if involved at all, sees only what you expose to it. With the MCP server, the interface is a tool list generated from OpenAPI specs and handed to an LLM client, and the model chooses which tool to call. The SDK gives you explicit control and ordinary code review; the MCP server gives you conversational reach across account, order and market-data operations without writing wrappers. Neither is a superset. If you already have SDK code in production, adding this server does not simplify it, it adds a second path to the same account. The migration table's own framing supports that reading: v1 parameters were custom schemas, v2 parameters align with Alpaca API specs. The project's value is in that alignment and in not maintaining hand-written tool definitions, not in capabilities the SDK lacks.

Licence, maintenance and what to check before adopting

The repository is MIT licensed, which permits commercial use and modification, though this is a description of the licence identifier and not legal advice; read the LICENSE file for the actual terms. On maintenance, the material available here shows a last push in September 2026 and no retrieved releases, so there is no published release cadence to point at. The upgrade guide is the strongest maintenance signal: the maintainers documented a breaking rewrite in detail and kept v1 on PyPI, which is more than many projects do. The cost you should budget for is reconfiguration, not code. Every client you use needs the new command and args, a restart, and a fresh session, and any custom instructions mentioning v1 tool names need editing. Before adopting, confirm three things against the repository: the current toolset names for ALPACA_TOOLSETS, the exact tool list the server exposes for your account type, and whether your client is one of the ones the README names. If you are on v1 and cannot migrate this week, pin uvx alpaca-mcp-server==1.x.x serve and set a date to move.

Editorial conclusion

Adopt it if you run an MCP-capable client, hold an Alpaca paper account, and want account, order and market-data calls reachable without writing a client library. Do not adopt it if you have v1 prompts or scripts pinned to specific tool names and parameters, because the README states none of the v1 tools exist in v2. Before anything else, verify which toolsets your client actually needs, set ALPACA_TOOLSETS accordingly, and confirm the exposed tool list after a client restart.

Official sources

1. alpacahq/alpaca-mcp-server on GitHub
2. Issues
3. License: MIT
4. Project website
5. README