npm package: @ideadesignmedia/alpaca-mcp
Description: MCP server exposing Alpaca Trading v2 and Market Data APIs for stocks and options. No streaming. Auth via env or CLI.
Author: IdeaDesignMedia
Latest version: 1.0.1

# @ideadesignmedia/alpaca-mcp

MCP server that exposes Alpaca Trading v2 and Market Data for stocks and options. It assumes you have market data entitlements. No streaming is used. Responses are fetched and returned once complete.

Auth sources: CLI flags then env.

- Flags: `--key-id`, `--secret-key`, `--paper`
- Env: `ALPACA_KEY_ID`, `ALPACA_SECRET_KEY`, `ALPACA_PAPER=true|false`

Trading base URL is selected by paper flag. Market data base is always `https://data.alpaca.markets`.

## Install

```sh
npm i -g @ideadesignmedia/alpaca-mcp
```

## Usage

```sh
alpaca-mcp --paper   --key-id AK...   --secret-key SK...
```

You can also run it on demand without installing globally:

```sh
npx @ideadesignmedia/alpaca-mcp --paper --key-id AK... --secret-key SK...
```

Or via env:

```sh
ALPACA_PAPER=true ALPACA_KEY_ID=AK... ALPACA_SECRET_KEY=SK... alpaca-mcp
```

This starts an MCP server using `@ideadesignmedia/open-ai.js`. The transport is stdio; configure your MCP client to launch this binary and communicate over standard input/output.

## MCP Client Configuration

Add the server entry to your MCP client configuration. The example below uses a generic JSON layout; adjust to match your client's configuration format.

```jsonc
{
  "servers": [
    {
      "id": "alpaca",
      "name": "Alpaca Trading",
      "command": "npx",
      "args": [
        "@ideadesignmedia/alpaca-mcp",
        "--paper",
        "--key-id",
        "AK...",
        "--secret-key",
        "SK..."
      ],
      "env": {
        "ALPACA_PAPER": "true"
      }
    }
  ]
}
```

If your client supports environment-variable secrets, prefer setting `ALPACA_KEY_ID` and `ALPACA_SECRET_KEY` through its secret manager instead of passing them as command arguments.

## Tools

Trading micro tools:
- `alpaca.get_account`, `alpaca.get_account_config`, `alpaca.update_account_config`, `alpaca.list_account_activities`
- `alpaca.list_assets`, `alpaca.get_asset`
- `alpaca.list_positions`, `alpaca.get_position`, `alpaca.close_position`, `alpaca.close_all_positions`
- `alpaca.create_order`, `alpaca.get_order`, `alpaca.list_orders`, `alpaca.cancel_order`, `alpaca.cancel_all_orders`, `alpaca.replace_order`
- `alpaca.list_watchlists`, `alpaca.get_watchlist`, `alpaca.get_watchlist_by_name`, `alpaca.create_watchlist`, `alpaca.update_watchlist`, `alpaca.delete_watchlist`, `alpaca.add_to_watchlist`, `alpaca.remove_from_watchlist`
- `alpaca.get_clock`, `alpaca.get_calendar`
- `alpaca.get_portfolio_history`
- `alpaca.list_announcements`

Market data micro tools:
- Stocks latest: `alpaca.data.stocks.latest_bar`, `alpaca.data.stocks.latest_quote`, `alpaca.data.stocks.latest_trade`, `alpaca.data.stocks.snapshot`, `alpaca.data.stocks.snapshots`
- Stocks historical: `alpaca.data.stocks.bars`, `alpaca.data.stocks.quotes`, `alpaca.data.stocks.trades`
- Options latest: `alpaca.data.options.snapshots`, `alpaca.data.options.latest_trades`, `alpaca.data.options.latest_quotes`, `alpaca.data.options.chain`
- Options historical: `alpaca.data.options.bars`, `alpaca.data.options.trades`, `alpaca.data.options.quotes`
- News: `alpaca.data.news`
- Corporate actions: `alpaca.data.corporate_actions`

Macro tools:
- `alpaca.get_stock_info` summary of asset meta, snapshot, latests, short history, news, corporate actions
- `alpaca.account_overview` account, open orders, positions, clock
- `alpaca.lookup_asset` convenience asset search

All tools are non streaming. Large result sets are paged. You can pass page_token on historical endpoints that support it.

## Security

No keys are logged. Missing credentials produce a clear error. No persistence is used.

## License

MIT