Skip to content
Back to search

alpaca-mcp-server

Alpaca’s official MCP Server lets you trade stocks, ETFs, crypto, and options, run data analysis, and build strategies in plain English directly from your favorite LLM tools and IDEs

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/alpacahq/alpaca-mcp-server with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/alpacahq/alpaca-mcp-server'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/alpacahq--alpaca-mcp-server/badge.svg)](/listings/alpacahq--alpaca-mcp-server)

HTML

<a href="/listings/alpacahq--alpaca-mcp-server"><img src="/api/listings/alpacahq--alpaca-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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**.

Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (Mac) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

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

Claude Mobile

Claude Mobile requires a remote MCP server. This package does not configure remote MCP authentication, so do not expose it directly to the public internet with your Alpaca API keys. Use the local stdio setup from a supported desktop client.

ChatGPT

ChatGPT requires a remote MCP server. This package does not configure remote MCP authentication, so do not expose it directly to the public internet with your Alpaca API keys. Use the local stdio setup from a supported desktop client.

Cursor

Install from the [Cursor Directory](https://cursor.directory/mcp/alpaca) in a few clicks, or add to `~/.cursor/mcp.json`:

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

VS Code

Create `.vscode/mcp.json` in your project root. See the [official docs](https://code.visualstudio.com/docs/copilot/chat/mcp-servers).

{
  "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](https://www.jetbrains.com/help/ai-assistant/configure-an-mcp-server.html).

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.

Antigravity CLI

See the [Antigravity MCP docs](https://antigravity.google/docs/mcp).

Add to `~/.gemini/antigravity-cli/mcp_config.json` (global) or `.agents/mcp_config.json` (workspace):

{
  "mcpServers": {
    "alpaca": {
      "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"
      ]
    }
  }
}

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 627 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <p align="center">
  2. <img src="https://raw.githubusercontent.com/alpacahq/alpaca-mcp-server/main/assets/01-primary-alpaca-logo.png" alt="Alpaca logo" width="220">
  3. </p>
  4. <div align="center">
  5. <a href="https://x.com/alpacahq?lang=en" target="_blank"><img src="https://img.shields.io/badge/X-DCDCDC?logo=x&logoColor=000" alt="X"></a>
  6. <a href="https://www.reddit.com/r/alpacamarkets/" target="_blank"><img src="https://img.shields.io/badge/Reddit-DCDCDC?logo=reddit&logoColor=000" alt="Reddit"></a>
  7. <a href="https://alpaca.markets/slack" target="_blank"><img src="https://img.shields.io/badge/Slack-DCDCDC?logo=slack&logoColor=000" alt="Slack"></a>
  8. <a href="https://www.linkedin.com/company/alpacamarkets/" target="_blank"><img src="https://img.shields.io/badge/LinkedIn-DCDCDC" alt="LinkedIn"></a>
  9. <a href="https://forum.alpaca.markets/" target="_blank"><img src="https://img.shields.io/badge/Forum-DCDCDC?logo=discourse&logoColor=000" alt="Forum"></a>
  10. <a href="https://docs.alpaca.markets/docs/getting-started" target="_blank"><img src="https://img.shields.io/badge/Docs-DCDCDC" alt="Docs"></a>
  11. <a href="https://alpaca.markets/sdks/python/" target="_blank"><img src="https://img.shields.io/badge/Python_SDK-DCDCDC?logo=python&logoColor=000" alt="Python SDK"></a>
  12. </div>
  13. <p align="center">
  14. A comprehensive Model Context Protocol (MCP) server for Alpaca's Trading API. Enable natural language trading operations through AI assistants like Claude, Cursor, and VS Code. Supports stocks, options, crypto, portfolio management, and real-time market data.
  15. </p>
  16. > **Alpaca MCP Server v2 is here.** This version is a complete rewrite built with FastMCP and OpenAPI. If you're upgrading from v1, please read the [Upgrade Guide](#upgrading-from-v1) — tool names, parameters, and configuration have changed.
  17. ## Table of Contents
  18. - [Upgrading from V1](#upgrading-from-v1)
  19. - [Prerequisites](#prerequisites)
  20. - [Getting Your API Keys](#getting-your-api-keys)
  21. - [Setup](#setup)
  22. - [Configuration](#configuration)
  23. - [Features](#features)
  24. - [Example Prompts](#example-prompts)
  25. - [Available Tools](#available-tools)
  26. - [Testing](#testing)
  27. - [Project Structure](#project-structure)
  28. - [Troubleshooting](#troubleshooting)
  29. - [Disclosure](#disclosure)
  30. ---
  31. ## Upgrading from V1
  32. V2 is a **complete rewrite** built with FastMCP and OpenAPI. **None of the V1 tools exist in V2** — tool names, parameters, and schemas have changed. You cannot use V2 as a drop-in replacement if your setup depends on specific V1 tool names or parameters.
  33. ### What changes
  34. | Aspect | V1 | V2 |
  35. | ------------------ | -------------------------------------- | -------------------------------------------------------------------------------------------- |
  36. | **Tool names** | Hand-crafted (e.g. `get_account_info`) | Spec-derived with overrides (e.g. `get_account_info` — names may overlap but schemas differ) |
  37. | **Parameters** | Custom schemas | Aligned with Alpaca API specs |
  38. | **Configuration** | `.env` + `init` command | Env vars in MCP client config only |
  39. | **Tool filtering** | Not supported | `ALPACA_TOOLSETS` env var |
  40. | **Whitelisting** | Not supported | Use `ALPACA_TOOLSETS` to restrict tools |
  41. ### How to avoid V1-style usage in V2
  42. 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:
  43. 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.
  44. 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.
  45. 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.
  46. 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.
  47. 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](#toolset-filtering) for the list of toolsets.
  48. ### Summary
  49. Assume **no backward compatibility** with V1. Reconfigure your MCP client for V2, restart it, and use a fresh session. Check the [Available Tools](#available-tools) section for the current tool list.
  50. ### If you had custom V1 workflows
  51. 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](#available-tools) listed below and the current parameter schemas exposed by the server.
  52. ### Staying on V1
  53. If you need to stay on V1, pin to the last V1 release (e.g. `uvx alpaca-mcp-server==1.x.x serve`) in your MCP client config. V1 remains available on PyPI for existing setups.
  54. ---
  55. ## Prerequisites
  56. - **Python 3.10+** ([installation guide](https://www.python.org/downloads/))
  57. - **uv** ([installation guide](https://docs.astral.sh/uv/getting-started/installation/))
  58. - **Alpaca Trading API keys** (free paper trading account)
  59. - **MCP client** (Claude Desktop, Cursor, VS Code, etc.)
  60. ## Getting Your API Keys
  61. 1. Visit the [Alpaca Dashboard](https://app.alpaca.markets/paper/dashboard/overview)
  62. 2. Create a free paper trading account
  63. 3. Generate API keys from the dashboard
  64. ## Setup
  65. 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**.
  66. ### Claude Desktop
  67. Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (Mac) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
  68. ```json
  69. {
  70. "mcpServers": {
  71. "alpaca": {
  72. "command": "uvx",
  73. "args": ["alpaca-mcp-server"],
  74. "env": {
  75. "ALPACA_API_KEY": "your_alpaca_api_key",
  76. "ALPACA_SECRET_KEY": "your_alpaca_secret_key"
  77. }
  78. }
  79. }
  80. }
  81. ```
  82. ### Claude Mobile
  83. Claude Mobile requires a remote MCP server. This package does not configure remote MCP authentication, so do not expose it directly to the public internet with your Alpaca API keys. Use the local stdio setup from a supported desktop client.
  84. ### ChatGPT
  85. ChatGPT requires a remote MCP server. This package does not configure remote MCP authentication, so do not expose it directly to the public internet with your Alpaca API keys. Use the local stdio setup from a supported desktop client.
  86. ### Cursor
  87. Install from the [Cursor Directory](https://cursor.directory/mcp/alpaca) in a few clicks, or add to `~/.cursor/mcp.json`:
  88. ```json
  89. {
  90. "mcpServers": {
  91. "alpaca": {
  92. "command": "uvx",
  93. "args": ["alpaca-mcp-server"],
  94. "env": {
  95. "ALPACA_API_KEY": "your_alpaca_api_key",
  96. "ALPACA_SECRET_KEY": "your_alpaca_secret_key"
  97. }
  98. }
  99. }
  100. }
  101. ```
  102. ### VS Code
  103. Create `.vscode/mcp.json` in your project root. See the [official docs](https://code.visualstudio.com/docs/copilot/chat/mcp-servers).
  104. ```json
  105. {
  106. "servers": {
  107. "alpaca": {
  108. "type": "stdio",
  109. "command": "uvx",
  110. "args": ["alpaca-mcp-server"],
  111. "env": {
  112. "ALPACA_API_KEY": "your_alpaca_api_key",
  113. "ALPACA_SECRET_KEY": "your_alpaca_secret_key"
  114. }
  115. }
  116. }
  117. }
  118. ```
  119. ### PyCharm
  120. See the [official guide](https://www.jetbrains.com/help/ai-assistant/configure-an-mcp-server.html).
  121. 1. Go to File → Settings → Tools → Model Context Protocol (MCP)
  122. 2. Add a new server:
  123. - **Type**: stdio
  124. - **Command**: uvx
  125. - **Arguments**: alpaca-mcp-server
  126. 3. Set environment variables:
  127. ```
  128. ALPACA_API_KEY=your_alpaca_api_key
  129. ALPACA_SECRET_KEY=your_alpaca_secret_key
  130. ```
  131. ### Claude Code
  132. ```bash
  133. claude mcp add alpaca --scope user --transport stdio uvx alpaca-mcp-server \
  134. --env ALPACA_API_KEY=your_alpaca_api_key \
  135. --env ALPACA_SECRET_KEY=your_alpaca_secret_key
  136. ```
  137. Verify with `/mcp` in the Claude Code CLI.
  138. ### Antigravity CLI
  139. See the [Antigravity MCP docs](https://antigravity.google/docs/mcp).
  140. Add to `~/.gemini/antigravity-cli/mcp_config.json` (global) or `.agents/mcp_config.json` (workspace):
  141. ```json
  142. {
  143. "mcpServers": {
  144. "alpaca": {
  145. "command": "uvx",
  146. "args": ["alpaca-mcp-server"],
  147. "env": {
  148. "ALPACA_API_KEY": "your_alpaca_api_key",
  149. "ALPACA_SECRET_KEY": "your_alpaca_secret_key"
  150. }
  151. }
  152. }
  153. }
  154. ```
  155. ### Docker
  156. ```bash
  157. git clone https://github.com/alpacahq/alpaca-mcp-server.git
  158. cd alpaca-mcp-server
  159. docker build -t mcp/alpaca:latest .
  160. ```
  161. Add to your MCP client config:
  162. ```json
  163. {
  164. "mcpServers": {
  165. "alpaca": {
  166. "command": "docker",
  167. "args": [
  168. "run", "--rm", "-i",
  169. "-e", "ALPACA_API_KEY=your_key",
  170. "-e", "ALPACA_SECRET_KEY=your_secret",
  171. "-e", "ALPACA_PAPER_TRADE=true",
  172. "mcp/alpaca:latest"
  173. ]
  174. }
  175. }
  176. }
  177. ```
  178. ## Configuration
  179. All configuration is through environment variables set in your MCP client config. No files are written to disk.
  180. | Variable | Required | Default | Description |
  181. | -------------------- | -------- | ------- | ------------------------------------------ |
  182. | `ALPACA_API_KEY` | Yes | — | Your Alpaca API key |
  183. | `ALPACA_SECRET_KEY` | Yes | — | Your Alpaca secret key |
  184. | `ALPACA_PAPER_TRADE` | No | `true` | Set to `false` for live trading |
  185. | `ALPACA_TOOLSETS` | No | all | Comma-separated list of toolsets to enable |
  186. ### Switching to Live Trading
  187. Update the `env` block in your MCP client config and restart:
  188. ```json
  189. {
  190. "env": {
  191. "ALPACA_API_KEY": "your_live_api_key",
  192. "ALPACA_SECRET_KEY": "your_live_secret_key",
  193. "ALPACA_PAPER_TRADE": "false"
  194. }
  195. }
  196. ```
  197. ### Toolset Filtering
  198. By default, all tools are enabled. To limit the server to specific toolsets, set `ALPACA_TOOLSETS`:
  199. ```json
  200. {
  201. "env": {
  202. "ALPACA_API_KEY": "...",
  203. "ALPACA_SECRET_KEY": "...",
  204. "ALPACA_TOOLSETS": "stock-data,crypto-data"
  205. }
  206. }
  207. ```
  208. Available toolsets:
  209. | Toolset | Description |
  210. | ------------------- | ------------------------------------------------------------- |
  211. | `account` | Account info, config, portfolio history, activities |
  212. | `trading` | Orders, positions, exercise options |
  213. | `watchlists` | Watchlist CRUD operations |
  214. | `assets` | Asset lookup, option contracts, calendar, clock |
  215. | `stock-data` | Stock bars, quotes, trades, snapshots, screeners |
  216. | `crypto-data` | Crypto bars, quotes, trades, snapshots, orderbooks |
  217. | `options-data` | Option bars, quotes, trades, snapshots, chain, exchange codes |
  218. | `corporate-actions` | Corporate action announcements |
  219. | `news` | News articles for stocks and crypto |
  220. | `fixed-income-data` | Fixed income (bond/treasury) quotes |
  221. | `locates` | Short-sale locate requests and quotes |
  222. ### ReadMe Docs MCP
  223. Docs are scoped to the Trading API, Market Data API, and Authentication API specs; Broker API endpoint docs are intentionally excluded from this server.
  224. If the ReadMe MCP lookup fails, tool responses include fallback links to Alpaca's public docs plus `llms.txt` and `llms-full.txt`.
  225. ## Features
  226. - **Market Data** — Real-time quotes, trades, and price bars for stocks, crypto, and options. Historical data with flexible timeframes. Option Greeks and implied volatility.
  227. - **Account Management** — View balances, buying power, account status, and portfolio history.
  228. - **Order Management** — Place market, limit, stop, stop-limit, and trailing-stop orders for stocks, crypto, and options. Cancel orders individually or in bulk.
  229. - **Options Trading** — Search contracts by expiration/strike/type. Place single-leg or multi-leg strategies. Get latest quotes, Greeks, and IV.
  230. - **Crypto Trading** — Market, limit, and stop-limit orders with GTC/IOC. Quantity or notional-based.
  231. - **Position Management** — View, close, or liquidate positions. Exercise option contracts.
  232. - **News** — News articles filterable by ticker and date range.
  233. - **Market Status** — Market open/close times, calendar, corporate actions.
  234. - **Watchlists** — Create, update, and manage watchlists.
  235. - **Asset Search** — Query details for stocks, ETFs, crypto, and options with filtering.
  236. ## Example Prompts
  237. **Basic Trading**
  238. 1. What's my current account balance and buying power on Alpaca?
  239. 2. Show me my current positions in my Alpaca account.
  240. 3. Buy 5 shares of AAPL at market price.
  241. 4. Sell 5 shares of TSLA with a limit price of $300.
  242. 5. Cancel all open stock orders.
  243. 6. Cancel the order with ID abc123.
  244. 7. Liquidate my entire position in GOOGL.
  245. 8. Close 10% of my position in NVDA.
  246. 9. Place a limit order to buy 100 shares of MSFT at $450.
  247. 10. Place a market order to sell 25 shares of META.
  248. **Crypto Trading**
  249. 1. Place a market order to buy 0.01 ETH/USD.
  250. 2. Place a limit order to sell 0.01 BTC/USD at $110,000.
  251. **Option Trading**
  252. 1. Show me available option contracts for AAPL expiring next month.
  253. 2. Get the latest quote for the AAPL250613C00200000 option.
  254. 3. Retrieve the option snapshot for the SPY250627P00400000 option.
  255. 4. Liquidate my position in 2 contracts of QQQ calls expiring next week.
  256. 5. Place a market order to buy 1 call option on AAPL expiring next Friday.
  257. 6. What are the option Greeks for the TSLA250620P00500000 option?
  258. 7. Find TSLA option contracts with strike prices within 5% of the current market price.
  259. 8. Get SPY call options expiring the week of June 16th, 2025, within 10% of market price.
  260. 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.
  261. 10. Exercise my NVDA call option contract NVDA250919C001680.
  262. **Market Information**
  263. > To access the latest 15-minute data, you need to subscribe to the [Algo Trader Plus Plan](https://alpaca.markets/data).
  264. >
  265. > 1. What are the market open and close times today?
  266. > 2. Show me the market calendar for next week.
  267. > 3. Show me recent cash dividends and stock splits for AAPL, MSFT, and GOOGL in the last 3 months.
  268. > 4. Get all corporate actions for SPY including dividends, splits, and any mergers in the past year.
  269. > 5. What are the upcoming corporate actions scheduled for SPY in the next 6 months?
  270. **Historical & Real-time Data**
  271. 1. Show me AAPL's daily price history for the last 5 trading days.
  272. 2. What was the closing price of TSLA yesterday?
  273. 3. Get the latest bar for GOOGL.
  274. 4. What was the latest trade price for NVDA?
  275. 5. Show me the most recent quote for MSFT.
  276. 6. Retrieve the last 100 trades for AMD.
  277. 7. Show me 1-minute bars for AMZN from the last 2 hours.
  278. 8. Get 5-minute intraday bars for TSLA from last Tuesday through last Friday.
  279. 9. Get a comprehensive stock snapshot for AAPL showing latest quote, trade, minute bar, daily bar, and previous daily bar all in one view.
  280. 10. Compare market snapshots for TSLA, NVDA, and MSFT to analyze their current bid/ask spreads, latest trade prices, and daily performance.
  281. **Orders**
  282. 1. Show me all my open and filled orders from this week.
  283. 2. What orders do I have for AAPL?
  284. 3. List all limit orders I placed in the past 3 days.
  285. 4. Filter all orders by status: filled.
  286. 5. Get me the order history for yesterday.
  287. **Watchlists**
  288. > At this moment, you can only view and update trading watchlists created via Alpaca's Trading API through the API itself
  289. >
  290. > 1. Create a new watchlist called "Tech Stocks" with AAPL, MSFT, and NVDA.
  291. > 2. Update my "Tech Stocks" watchlist to include TSLA and AMZN.
  292. > 3. What stocks are in my "Dividend Picks" watchlist?
  293. > 4. Remove META from my "Growth Portfolio" watchlist.
  294. > 5. List all my existing watchlists.
  295. **Asset Information**
  296. 1. Search for details about the asset 'AAPL'.
  297. 2. Show me the top 5 tradable crypto assets by trading volume.
  298. 3. Get all NASDAQ active US equity assets and filter the results to show only tradable securities
  299. **Combined Scenarios**
  300. 1. Get today's market clock and show me my buying power before placing a limit buy order for TSLA at $340.
  301. 2. Place a bull call spread with SPY July 3rd options: sell one 5% above and buy one 3% below the current SPY price.
  302. ## Available Tools
  303. **Account & Portfolio**
  304. - `get_account_info` — Balance, margin, and account status
  305. - `get_account_config` — Trading restrictions, margin settings, PDT checks
  306. - `update_account_config` — Update account configuration settings
  307. - `get_portfolio_history` — Equity and P/L over time
  308. - `get_account_activities` — Fills, dividends, transfers
  309. - `get_account_activities_by_type` — Activities filtered by type
  310. **Trading (Orders)**
  311. - `get_orders` — Retrieve orders with filters
  312. - `get_order_by_id` — Single order by ID
  313. - `get_order_by_client_id` — Single order by client order ID
  314. - `replace_order_by_id` — Replace an existing open order
  315. - `cancel_order_by_id` — Cancel a specific order
  316. - `cancel_all_orders` — Cancel all open orders
  317. - `place_stock_order` — Stocks/ETFs (market, limit, stop, stop-limit, trailing-stop, brackets)
  318. - `place_crypto_order` — Crypto (market, limit, stop-limit)
  319. - `place_option_order` — Options (single-leg or multi-leg)
  320. **Positions**
  321. - `get_all_positions` — All current positions
  322. - `get_open_position` — Details for a specific position
  323. - `close_position` — Close a specific position
  324. - `close_all_positions` — Liquidate entire portfolio
  325. - `exercise_options_position` — Exercise a held option contract
  326. - `do_not_exercise_options_position` — Do-not-exercise instruction
  327. **Watchlists**
  328. - `create_watchlist` — Create a new watchlist
  329. - `get_watchlists` — List all watchlists
  330. - `get_watchlist_by_id` — Get a specific watchlist
  331. - `update_watchlist_by_id` — Update a watchlist
  332. - `delete_watchlist_by_id` — Delete a watchlist
  333. - `add_asset_to_watchlist_by_id` — Add an asset to a watchlist
  334. - `remove_asset_from_watchlist_by_id` — Remove an asset from a watchlist
  335. **Assets & Market Info**
  336. - `get_all_assets` — List assets with optional filtering
  337. - `get_asset` — Detailed info for a specific asset
  338. - `get_option_contracts` — Option contracts for underlying symbol(s)
  339. - `get_option_contract` — Single option contract by symbol or ID
  340. - `get_calendar` — Market calendar for a date range
  341. - `get_clock` — Current market status and next open/close
  342. - `get_corporate_action_announcements` — Corporate action announcements
  343. - `get_corporate_action_announcement` — Single announcement by ID
  344. **Stock Data**
  345. - `get_stock_bars` — Historical OHLCV bars
  346. - `get_stock_quotes` — Historical bid/ask quotes
  347. - `get_stock_trades` — Historical trades
  348. - `get_stock_latest_bar` — Latest minute bar
  349. - `get_stock_latest_quote` — Latest quote
  350. - `get_stock_latest_trade` — Latest trade
  351. - `get_stock_snapshot` — Comprehensive snapshot
  352. - `get_most_active_stocks` — Most active by volume/trade count
  353. - `get_market_movers` — Top gainers and losers
  354. **Crypto Data**
  355. - `get_crypto_bars` — Historical OHLCV bars
  356. - `get_crypto_quotes` — Historical quotes
  357. - `get_crypto_trades` — Historical trades
  358. - `get_crypto_latest_bar` — Latest minute bar
  359. - `get_crypto_latest_quote` — Latest quote
  360. - `get_crypto_latest_trade` — Latest trade
  361. - `get_crypto_snapshot` — Comprehensive snapshot
  362. - `get_crypto_latest_orderbook` — Latest orderbook
  363. **Options Data**
  364. - `get_option_bars` — Historical OHLCV bars
  365. - `get_option_trades` — Historical trades
  366. - `get_option_latest_trade` — Latest trade
  367. - `get_option_latest_quote` — Latest quote with bid/ask and exchange info
  368. - `get_option_snapshot` — Snapshot with Greeks and IV
  369. - `get_option_chain` — Full option chain for an underlying
  370. - `get_option_exchange_codes` — Exchange code to name mapping
  371. **Corporate Actions**
  372. - `get_corporate_actions` — Corporate action announcements from market data
  373. **News**
  374. - `get_news` — News articles for stocks and crypto
  375. **Fixed Income Data**
  376. - `get_fixed_income_latest_quotes` — Latest quotes for fixed income securities by ISIN
  377. **Locates (Short Selling)** — not available in paper trading
  378. - `get_locates` — List locate requests filtered by status, symbol, or date range
  379. - `create_locate` — Create a locate request for a short sale
  380. - `get_locate` — Get a single locate request by ID
  381. - `get_locate_quotes` — Get locate availability and pricing for symbols
  382. **Documentation**
  383. - `search_alpaca_docs` — Search Alpaca documentation pages and guides
  384. - `fetch_alpaca_doc` — Fetch one Alpaca ReadMe documentation page by page ID
  385. - `search_alpaca_api_specs` — Search Alpaca API reference endpoints by topic, path, parameter, or schema term
  386. - `list_alpaca_api_endpoints` — List endpoints for one allowed Alpaca OpenAPI spec
  387. - `get_alpaca_endpoint_docs` — Fetch reference docs for one exact Alpaca API endpoint by method and path
  388. ## Testing
  389. The project includes a multi-layered test suite that runs in CI on every pull request:
  390. - **Integrity tests** — Validate consistency between OpenAPI specs, toolset definitions, and tool name/description overrides. No network or credentials required.
  391. - **Server construction tests** — Build the server with mocked credentials and verify the correct number of tools are exposed. No network required.
  392. - **Paper API integration tests** — Execute real calls against the Alpaca paper trading API, covering account info, market data, order lifecycle, watchlists, positions, and more. Requires `ALPACA_API_KEY` and `ALPACA_SECRET_KEY`.
  393. - **ReadMe integration tests** — Execute live documentation lookup calls against Alpaca's ReadMe MCP. Requires `ALPACA_RUN_README_INTEGRATION=true` when run locally.
  394. Run the full suite locally:
  395. ```bash
  396. # Core tests (no credentials needed)
  397. pytest tests/test_integrity.py tests/test_server_construction.py -v
  398. # Integration tests (requires paper API keys)
  399. ALPACA_API_KEY=... ALPACA_SECRET_KEY=... pytest tests/ -m integration -v
  400. # ReadMe docs integration tests (requires network, no Alpaca credentials)
  401. ALPACA_RUN_README_INTEGRATION=true pytest tests/test_readme_integration.py -v
  402. ```
  403. ## Project Structure
  404. ```
  405. alpaca-mcp-server/
  406. ├── src/
  407. │ └── alpaca_mcp_server/
  408. │ ├── __init__.py
  409. │ ├── cli.py ← CLI entry point
  410. │ ├── server.py ← FastMCP server built from OpenAPI specs
  411. │ ├── tool_registry.py ← Tool names, descriptions, and output risk classifications
  412. │ ├── toolsets.py ← Toolset → operationId allowlists
  413. │ ├── overrides.py ← Hand-crafted tools for complex trading endpoints
  414. │ ├── market_data_overrides.py ← Hand-crafted tools for historical data
  415. │ ├── readme_docs.py ← Read-only proxy tools for Alpaca ReadMe docs
  416. │ └── specs/
  417. │ ├── trading-api.json
  418. │ └── market-data-api.json
  419. ├── tests/
  420. │ ├── conftest.py ← Shared fixtures and paper-account cleanup
  421. │ ├── test_integrity.py ← Spec ↔ toolset ↔ names consistency checks
  422. │ ├── test_server_construction.py ← Server build verification
  423. │ ├── test_readme_integration.py ← Live ReadMe docs MCP integration tests
  424. │ └── test_paper_integration.py ← Paper API integration tests
  425. ├── scripts/
  426. │ └── sync-specs.sh ← Download latest OpenAPI specs
  427. ├── .github/
  428. │ └── workflows/
  429. │ ├── ci.yml ← CI pipeline (core + integration)
  430. │ └── publish-pypi.yml ← PyPI publish on GitHub Release
  431. ├── AGENTS.md ← Instructions for coding agents
  432. ├── pyproject.toml
  433. └── README.md
  434. ```
  435. ## Troubleshooting
  436. - **uv/uvx not found**: Install uv from the official guide ([https://docs.astral.sh/uv/getting-started/installation/](https://docs.astral.sh/uv/getting-started/installation/)) and then restart your terminal so `uv`/`uvx` are on PATH.
  437. - **Credentials missing**: Set `ALPACA_API_KEY` and `ALPACA_SECRET_KEY` in the client's `env` block. Paper mode default is `ALPACA_PAPER_TRADE = True`.
  438. - **Client didn't pick up new config**: Restart the client (Cursor, Claude Desktop, VS Code) after changes.
  439. - **HTTP port conflicts**: If using `--transport streamable-http`, change `--port` to a free port.
  440. ## Disclosure
  441. Insights generated by our MCP server and connected AI agents are for educational and informational purposes only and should not be taken as investment advice. Alpaca does not recommend any specific securities or investment strategies.Please conduct your own due diligence before making any decisions. All firms mentioned operate independently and are not liable for one another.
  442. Options trading is not suitable for all investors due to its inherent high risk, which can potentially result in significant losses. Please read Characteristics and Risks of Standardized Options ([Options Disclosure Document](https://www.theocc.com/company-information/documents-and-archives/options-disclosure-document?ref=alpaca.markets)) before investing in options.
  443. Alpaca does not prepare, edit, endorse, or approve Third Party Content. Alpaca does not guarantee the accuracy, timeliness, completeness or usefulness of Third Party Content, and is not responsible or liable for any content, advertising, products, or other materials on or available from third party sites.
  444. All investments involve risk, and the past performance of a security, or financial product does not guarantee future results or returns. There is no guarantee that any investment strategy will achieve its objectives. Please note that diversification does not ensure a profit, or protect against loss. There is always the potential of losing money when you invest in securities, or other financial products. Investors should consider their investment objectives and risks carefully before investing.
  445. The algorithm's calculations are based on historical and real-time market data but may not account for all market factors, including sudden price moves, liquidity constraints, or execution delays. Model assumptions, such as volatility estimates and dividend treatments, can impact performance and accuracy. Trades generated by the algorithm are subject to brokerage execution processes, market liquidity, order priority, and timing delays. These factors may cause deviations from expected trade execution prices or times. Users are responsible for monitoring algorithmic activity and understanding the risks involved. Alpaca is not liable for any losses incurred through the use of this system.
  446. Past hypothetical backtest results do not guarantee future returns, and actual results may vary from the analysis.
  447. The Paper Trading API is offered by AlpacaDB, Inc. and does not require real money or permit a user to transact in real securities in the market. Providing use of the Paper Trading API is not an offer or solicitation to buy or sell securities, securities derivative or futures products of any kind, or any type of trading or investment advice, recommendation or strategy, given or in any manner endorsed by AlpacaDB, Inc. or any AlpacaDB, Inc. affiliate and the information made available through the Paper Trading API is not an offer or solicitation of any kind in any jurisdiction where AlpacaDB, Inc. or any AlpacaDB, Inc. affiliate (collectively, "Alpaca") is not authorized to do business.
  448. Securities brokerage services are provided by Alpaca Securities LLC ("Alpaca Securities"), member [FINRA](https://www.finra.org/)/[SIPC](https://www.sipc.org/), a wholly-owned subsidiary of AlpacaDB, Inc. Technology and services are offered by AlpacaDB, Inc.
  449. Cryptocurrency services are provided by Alpaca Crypto LLC ("Alpaca Crypto"), a FinCEN registered money services business (NMLS # 2160858), and a wholly-owned subsidiary of AlpacaDB, Inc. Alpaca Crypto is not a member of SIPC or FINRA. Cryptocurrencies are not stocks and your cryptocurrency investments are not protected by either FDIC or SIPC. Cryptocurrency assets are highly volatile and speculative, involving substantial risk of loss, and are not insured by the FDIC or any government agency. Customers should be aware of the various risks prior to engaging these services, including potential loss of principal, cybersecurity considerations, regulatory developments, and the evolving nature of digital asset technology. For additional information on the risks of cryptocurrency, please click [here](https://files.alpaca.markets/disclosures/library/CryptoRiskDisclosures.pdf).
  450. This is not an offer, solicitation of an offer, or advice to buy or sell securities or cryptocurrencies or open a brokerage account or cryptocurrency account in any jurisdiction where Alpaca Securities or Alpaca Crypto, respectively, are not registered or licensed, as applicable.
  451. ## Privacy Policy
  452. For information about how Alpaca handles your data, please review:
  453. - [Privacy Policy](https://s3.amazonaws.com/files.alpaca.markets/disclosures/PrivacyPolicy.pdf)
  454. - [Disclosure Library](https://alpaca.markets/disclosures)
  455. ### Data Collection
  456. - **What is collected**: User agent string (`APCA-MCP-TRADING/<version>`) for API calls
  457. - **How it's used**: To identify MCP server usage and improve user experience
  458. - **Third-party sharing**: Not shared with third parties
  459. - **Retention**: Retained per Alpaca's standard data retention policy
  460. - **Opt-out**: Set the `ALPACA_MCP_USER_AGENT` environment variable to an empty string; no User-Agent header will be sent
  461. ## Security Notice
  462. 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.
  463. **HTTP Transport Security**: Streamable HTTP defaults to localhost (`127.0.0.1:8000`) and validates `Host` and `Origin` headers. Docker defaults to stdio. Helm defaults to ClusterIP HTTP with ingress off. Binding to `0.0.0.0` does not provide authentication. This package does not configure MCP OAuth, so do not expose it directly to the public internet. Operators that provide standards-based MCP authentication must also set FastMCP's `FASTMCP_HTTP_ALLOWED_HOSTS` to the exact public hostnames.
  464. ## Support
  465. For issues or questions, please contact us at [support@alpaca.markets](mailto:support@alpaca.markets).
  466. GitHub Issues: [https://github.com/alpacahq/alpaca-mcp-server/issues](https://github.com/alpacahq/alpaca-mcp-server/issues)
  467. GitHub Pull requests: [https://github.com/alpacahq/alpaca-mcp-server/pulls](https://github.com/alpacahq/alpaca-mcp-server/pulls)
  468. ### MCP Registry Metadata
  469. mcp-name: io.github.alpacahq/alpaca-mcp-server

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.