Trading Server

A Model Context Protocol (MCP) server that exposes Alpaca paper trading tools via SSE transport. Designed to serve Claude Desktop (over LAN) and n8n (localhost).

Features

• SSE Transport: Server-Sent Events for real-time communication
• Two Core Tools:
  • get_positions — Retrieve all open positions from Alpaca
  • get_account — Get account summary and buying power
• Multi-client Support: Claude Desktop (LAN) + n8n (localhost)
• PM2 Integration: Production deployment on Mac Mini

Quick Start

Setup

1. Clone and install:

   npm install
   

2. Configure environment:

   cp .env.example .env
   # Edit .env with your Alpaca API credentials
   

3. Run locally:

   npm run dev
   

   Or start with PM2:

   npm run pm2:start
   

Environment Variables

• APCA_API_KEY_ID — Your Alpaca API key
• APCA_API_SECRET_KEY — Your Alpaca secret key
• PORT — Server port (default: 3100)
• NODE_ENV — Environment (production/development)

Architecture

src/
├── server.js           # Express + MCP SSE transport
├── tools/
│   └── alpaca.js       # Tool definitions and handlers
└── alpaca/
    └── client.js       # Reusable Alpaca API client

Server Details

• Port: 3100
• Transport: Server-Sent Events (SSE)
• Base URL: https://paper-api.alpaca.markets/v2
• Auth: APCA-API-KEY-ID and APCA-API-SECRET-KEY headers

Tools

get_positions

Fetches all open positions from your Alpaca paper account.

Returns:

{
  "positions": [
    {
      "symbol": "ETHUSD",
      "qty": 1.5,
      "avg_fill_price": 2800.00,
      "current_price": 2850.00,
      "side": "long",
      "unrealized_pl": 75.00,
      "unrealized_plpc": 0.0267
    }
  ]
}

get_account

Fetches account summary including buying power and cash balance.

Returns:

{
  "account": {
    "id": "...",
    "account_number": "...",
    "buying_power": 25000.00,
    "cash": 10000.00,
    "portfolio_value": 35000.00,
    "multiplier": 1,
    "equity": 35000.00,
    "last_equity": 35000.00
  }
}

Development

Watch mode with auto-restart:

npm run dev

View PM2 logs:

npm run pm2:logs

Restart service:

npm run pm2:restart

Production Deployment

On Mac Mini, use PM2 ecosystem file:

npm run pm2:start

The process will:

• Auto-restart on crashes
• Start on system boot (if configured)
• Rotate logs daily
• Maintain error and output logs

Connecting Clients

Claude Desktop

Configure in claude_desktop_config.json:

{
  "mcpServers": {
    "trading": {
      "command": "node",
      "args": ["/path/to/mcp-trading-server/src/server.js"],
      "env": {
        "APCA_API_KEY_ID": "...",
        "APCA_API_SECRET_KEY": "..."
      }
    }
  }
}

n8n

Create HTTP Request node pointing to http://localhost:3100

Troubleshooting

Connection refused: Ensure server is running on port 3100

lsof -i :3100

Auth errors: Verify .env has valid Alpaca credentials

PM2 issues: Check logs

pm2 logs mcp-trading-server

License

MIT