Alpaca Finance API MCP Server Guide

export APCA_API_KEY_ID="PKYOURPAPERKEYID"
export APCA_API_SECRET_KEY="your-paper-secret-key"
export APCA_PAPER="true"
export MAX_ORDER_DOLLAR_LIMIT="500"

{
  "mcpServers": {
    "alpaca-finance": {
      "command": "node",
      "args": ["/opt/mcp-servers/alpaca/dist/index.js"],
      "env": {
        "APCA_API_KEY_ID": "PKYOURPAPERKEYID",
        "APCA_API_SECRET_KEY": "your-paper-secret-key",
        "APCA_PAPER": "true",
        "MAX_ORDER_DOLLAR_LIMIT": "500"
      }
    }
  }
}

{
  "mcpServers": {
    "alpaca-finance": {
      "command": "node",
      "args": ["./dist/index.js"],
      "env": {
        "APCA_API_KEY_ID": "PKYOURPAPERKEYID",
        "APCA_API_SECRET_KEY": "your-paper-secret-key",
        "APCA_PAPER": "true"
      }
    }
  }
}

[mcp_servers.alpaca_finance]
command = "node"
args = ["/opt/mcp-servers/alpaca/dist/index.js"]

[mcp_servers.alpaca_finance.env]
APCA_API_KEY_ID = "PKYOURPAPERKEYID"
APCA_API_SECRET_KEY = "your-paper-secret-key"
APCA_PAPER = "true"

import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
import Alpaca from '@alpacahq/alpaca-trade-api';

const isPaper = process.env.APCA_PAPER === 'true';
const maxOrderLimit = parseFloat(process.env.MAX_ORDER_DOLLAR_LIMIT || '500');

if (!isPaper) {
  process.stderr.write("FATAL ERROR: Alpaca MCP Server must run with APCA_PAPER='true'\n");
  process.exit(1);
}

const alpaca = new Alpaca({
  keyId: process.env.APCA_API_KEY_ID,
  secretKey: process.env.APCA_API_SECRET_KEY,
  paper: true
});

const server = new Server(
  { name: 'alpaca-finance-mcp', version: '1.0.0' },
  { capabilities: { tools: {} } }
);

server.setRequestHandler(ListToolsRequestSchema, async () => {
  return {
    tools: [
      {
        name: 'get_stock_quote',
        description: 'Fetch latest bid, ask, and last trade price for a US equity ticker.',
        inputSchema: {
          type: 'object',
          properties: {
            symbol: { type: 'string', description: 'Stock ticker symbol (e.g. AAPL, MSFT)' }
          },
          required: ['symbol']
        }
      },
      {
        name: 'get_account_balance',
        description: 'Retrieve current paper trading cash balance, buying power, and portfolio equity.',
        inputSchema: {
          type: 'object',
          properties: {}
        }
      },
      {
        name: 'place_paper_order',
        description: 'Submit a simulated paper equity order with strict dollar value limits.',
        inputSchema: {
          type: 'object',
          properties: {
            symbol: { type: 'string', description: 'Stock ticker symbol' },
            qty: { type: 'number', description: 'Number of whole shares to purchase' },
            side: { type: 'string', enum: ['buy', 'sell'], description: 'Order direction' },
            order_type: { type: 'string', enum: ['market', 'limit'], default: 'market' },
            limit_price: { type: 'number', description: 'Mandatory limit price if order_type is limit' }
          },
          required: ['symbol', 'qty', 'side']
        }
      }
    ]
  };
});

server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;

  try {
    if (name === 'get_stock_quote') {
      const symbol = (args?.symbol as string).toUpperCase();
      const quote = await alpaca.getLatestQuote(symbol);
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify({
              symbol,
              ask_price: quote.AskPrice,
              ask_size: quote.AskSize,
              bid_price: quote.BidPrice,
              bid_size: quote.BidSize,
              timestamp: quote.Timestamp
            }, null, 2)
          }
        ]
      };
    }

    if (name === 'get_account_balance') {
      const account = await alpaca.getAccount();
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify({
              status: account.status,
              currency: account.currency,
              buying_power: account.buying_power,
              cash: account.cash,
              portfolio_value: account.portfolio_value
            }, null, 2)
          }
        ]
      };
    }

    if (name === 'place_paper_order') {
      const symbol = (args?.symbol as string).toUpperCase();
      const qty = Number(args?.qty);
      const side = args?.side as 'buy' | 'sell';
      const orderType = (args?.order_type as 'market' | 'limit') || 'market';

      const quote = await alpaca.getLatestQuote(symbol);
      const estimatedCost = qty * quote.AskPrice;

      if (estimatedCost > maxOrderLimit) {
        return {
          isError: true,
          content: [
            {
              type: 'text',
              text: `Order rejected: Estimated cost (${estimatedCost.toFixed(2)}) exceeds maximum dollar limit (${maxOrderLimit.toFixed(2)}).`
            }
          ]
        };
      }

      const orderPayload: any = {
        symbol,
        qty,
        side,
        type: orderType,
        time_in_force: 'day'
      };

      if (orderType === 'limit') {
        if (!args?.limit_price) {
          throw new Error('Limit orders require a limit_price argument.');
        }
        orderPayload.limit_price = Number(args.limit_price);
      }

      const order = await alpaca.createOrder(orderPayload);

      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify({
              status: 'submitted',
              order_id: order.id,
              symbol: order.symbol,
              qty: order.qty,
              side: order.side,
              type: order.type
            }, null, 2)
          }
        ]
      };
    }

    throw new Error(`Tool ${name} is not recognized.`);
  } catch (err: any) {
    return {
      isError: true,
      content: [{ type: 'text', text: `Alpaca API Error: ${err.message}` }]
    };
  }
});

async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
}

main().catch((err) => {
  process.stderr.write(`Fatal error: ${err.message}\n`);
  process.exit(1);
});

{
  "jsonrpc": "2.0",
  "id": "alpaca-quote-42",
  "method": "tools/call",
  "params": {
    "name": "get_stock_quote",
    "arguments": {
      "symbol": "AAPL"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": "alpaca-quote-42",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\n  \"symbol\": \"AAPL\",\n  \"ask_price\": 224.50,\n  \"ask_size\": 100,\n  \"bid_price\": 224.48,\n  \"bid_size\": 200,\n  \"timestamp\": \"2026-10-09T20:30:00Z\"\n}"
      }
    ]
  }
}