Alpaca MCP Server: a v2 rewrite that trades through Claude, Cursor and VS Code

What the Alpaca MCP Server actually removes from your workflow

The server is Alpaca's official Model Context Protocol implementation for its Trading API. The problem it addresses is narrow and concrete: an LLM client such as Claude Desktop, Cursor or VS Code cannot call a brokerage REST API on its own. Someone has to describe each endpoint, its parameters and its response shape to the model. Alpaca ships that description as a server the client launches over stdio, so the tool list arrives with the connection instead of living in a prompt.

The audience is developers who already use Alpaca. The README's prerequisites list a Python 3.10+ interpreter, uv, Alpaca Trading API keys from a free paper account, and an MCP client. If you do not have an Alpaca account, this server has nothing to talk to. That is the boundary worth stating early, because the project name invites a broader reading than the code supports.

Coverage, per the README, spans stocks, options, crypto, portfolio management and real-time market data. The repository topics confirm the same set. What the server does not do is decide anything: it exposes endpoints as tools and the model chooses among them.

FastMCP plus OpenAPI specs: how v2 generates its tools

Version 2 is described as a complete rewrite built with FastMCP and OpenAPI. The dependency list in pyproject.toml backs that up, pinning fastmcp>=3.1.0,<4 alongside httpx, python-dotenv and click. The build configuration includes src/alpaca_mcp_server/specs/*.json in the wheel, which is where the spec files live that tool definitions are derived from.

That design choice explains the upgrade table in the README. V1 tools were hand-crafted, with custom schemas. V2 tool names are spec-derived with overrides, and parameters are aligned with Alpaca API specs. The README notes that names may overlap between versions, which is the trap: a tool called get_account_info can exist in both versions while accepting different parameters. A client that cached the old schema will call it with the wrong shape and get an error that looks like a server fault.

Configuration moved too. V1 used a .env file plus an init command. V2 reads environment variables from the MCP client config only, which the README frames as credentials being set in one place. Tool filtering is new: the ALPACA_TOOLSETS environment variable restricts which tools the server exposes, and the upgrade table lists whitelisting as unsupported in V1. Server-side filtering matters here because a client discovers whatever the server exposes, and there is no separate config file where you allowlist tool names.

Install Alpaca MCP Server and place a first paper order

The README's setup path has no init command and no .env file. You edit your MCP client's config, add the server as a command with environment variables, and restart the client. For Claude Desktop on macOS the file is ~/Library/Application Support/Claude/claude_desktop_config.json; on Windows it is %APPDATA%\Claude\claude_desktop_config.json.

The block below is the README's Claude Desktop example. uvx runs the published package, and the two environment variables carry your keys. Replace both placeholder values with keys generated from the Alpaca dashboard.

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

After saving the file, restart the client. The README is explicit that a restart is required so the client fetches the new tool list rather than a stale one, and that you should start a fresh chat because existing conversations may hold cached references to old tool names. If the server connected, the tool list in your client should show the v2 tools rather than anything you remember from v1.

If you want a container instead, the repository ships a Dockerfile that installs uv, syncs from uv.lock, and ends with an HTTP transport command. The CMD binds all interfaces and lets the platform supply the port.

CMD ["alpaca-mcp-server", "--transport", "streamable-http", "--host", "0.0.0.0"]

That HTTP transport is also the route the README gives for mobile. Alpaca does not provide a hosted remote MCP server, so the instructions say to host it yourself on a cloud provider and add it as a custom connector in Claude. There is no alpaca mcp url you can paste in; the URL is whatever your own deployment exposes.

The v1 to v2 break is the biggest risk in this repository

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. That is an unusually blunt warning, and it should be read as the project's own assessment rather than a formality.

Three things break together. Tool names change. Parameters move to API-aligned schemas. Configuration moves out of .env and the init command into client environment variables. If you wrote Cursor rules, Claude instructions or scripts that name a tool, the README tells you to treat them as obsolete and recreate them from the current tool list. The failure mode is quiet: the model keeps calling a name it learned from an old prompt, the server has no such tool, and the error surfaces as a failed request rather than as a configuration problem.

Staying on v1 is possible. The README suggests pinning to the last v1 release in your MCP client config, giving uvx alpaca-mcp-server==1.x.x serve as the shape, and notes that v1 remains available on PyPI. That is a real escape hatch, but it freezes you on the older schema while Alpaca's API specs move on, and the README does not document how long v1 will keep receiving fixes. Anyone with v1-dependent automation should treat the pin as a temporary state and budget the rewrite.

One more gap worth naming: the README does not document rollback. There is no described procedure for reverting a client to a previous server version beyond the pinning suggestion, and no migration tool that maps v1 tool calls to v2 equivalents. You reconstruct the mapping by hand from the available tools list.

Where the Alpaca MCP Server is the wrong choice

The server sits between an LLM and a brokerage account, and that position defines its limits. An LLM chooses which tool to call and with what arguments. For research prompts, reading account state or pulling market data, that is a reasonable division of labor. For anything where a wrong argument has a cost, the model is now in the execution path, and the README offers no guardrail beyond toolset filtering.

ALPACA_TOOLSETS restricts which tools the server exposes, which is the closest thing to a safety control documented here. It is a scope control, not a validation layer. It does not check order sizes, price bands or symbol allowlists. If you need those checks, they belong in code you write, not in a prompt.

There are two other cases where this is the wrong tool. If your workflow is a scheduled strategy that runs without a human in the loop, an MCP server is the wrong shape: nothing about the design assumes unattended execution, and the natural language layer adds a failure mode without adding capability. If you are not an Alpaca customer, the server is inert; it is an adapter for one brokerage's API, not a general market data gateway.

Finally, treat the beta classifier in pyproject.toml as a signal. The project labels itself Development Status :: 4 - Beta at version 2.3.1. The README's own upgrade guidance, which asks users to assume no backward compatibility, is consistent with that label.

Alpaca MCP Server against IBKR and Robinhood MCP servers

The alternatives people search for alongside this project are other brokers' MCP servers, and the difference is not feature lists. It is who publishes the server and what it is generated from.

Alpaca's server is first-party and spec-derived. The wheel ships JSON specs, tool names come from those specs with overrides, and parameters align with the published Alpaca API. That means the tool surface tracks the vendor's own API documentation, and an API change is a spec change rather than a hand-edit to a wrapper. The cost is the v1 to v2 break documented above: when the generation approach changes, the tool surface changes with it.

A community-built server for another broker usually starts from that broker's REST documentation and hand-writes tool definitions. That can be more forgiving across versions, because a maintainer can keep old tool names alive as aliases. It also means the tool schemas are one person's reading of an API, and they drift when the broker changes an endpoint. For Alpaca specifically, choosing a third-party wrapper over the official server buys you nothing except the risk of a stale schema.

The honest comparison is not Alpaca versus another broker. It is Alpaca MCP Server versus writing your own thin wrapper over the Alpaca Python SDK, which the repository's own requirements.txt still lists as a dependency. If you need three endpoints and strict control over arguments, a wrapper you own is simpler than a server that exposes the whole API surface.

Licence, maintenance and the cost of tracking v2

The project is MIT licensed, declared in both the LICENSE file at the repository root and the license field in pyproject.toml. MIT is permissive: you can use, modify and redistribute the code, including in commercial settings, provided the copyright notice and licence text travel with it. That covers the server code. It does not cover your relationship with Alpaca, which is governed by your brokerage agreement and the API terms, and it does not cover market data, which carries its own redistribution rules. Nothing here is legal advice; if you plan to redistribute a product built on this, read the Alpaca terms separately from the MIT text.

On maintenance, the last push to the default branch was on 2026-09-04, which is recent enough that the repository is not dormant. The README documents an upgrade path, the Dockerfile pins dependencies through uv.lock, and the pyproject dev extras include ruff, mypy and pytest, so the project carries tooling for its own checks. There are no retrieved releases, so version history has to be read from pyproject.toml, which currently declares 2.3.1.

The upgrade cost is the part to budget for. Because v2 derives tools from specs, a future v3 could repeat the v1-to-v2 pattern. Any prompt, rule file or script that hard-codes a tool name is a liability, and the README's advice to let the LLM discover tools from context is the cheaper posture. Keep your custom instructions free of specific tool names and the next rewrite costs you a restart instead of a rewrite.

Editorial conclusion

Adopt it if you already hold Alpaca API keys and want an LLM client to read positions, pull market data and place paper orders without writing a wrapper. Do not adopt it if your prompts, Cursor rules or scripts reference v1 tool names, because the README states plainly that none of the V1 tools exist in V2. Before connecting a funded account, verify three things: that your client is running the v2 tool list after a restart, which toolsets ALPACA_TOOLSETS leaves enabled, and whether ALPACA_PAPER is set so orders route to the paper endpoint.

Frequently asked questions

Official sources

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