# MCP 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**:
   ```bash
   npm install
   ```

2. **Configure environment**:
   ```bash
   cp .env.example .env
   # Edit .env with your Alpaca API credentials
   ```

3. **Run locally**:
   ```bash
   npm run dev
   ```

   Or start with PM2:
   ```bash
   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**:
```json
{
  "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**:
```json
{
  "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:
```bash
npm run dev
```

View PM2 logs:
```bash
npm run pm2:logs
```

Restart service:
```bash
npm run pm2:restart
```

## Production Deployment

On Mac Mini, use PM2 ecosystem file:

```bash
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`:
```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
```bash
lsof -i :3100
```

**Auth errors**: Verify `.env` has valid Alpaca credentials

**PM2 issues**: Check logs
```bash
pm2 logs mcp-trading-server
```

## License

MIT