thsdeveloper/alpaca-mcp-server

Alpaca MCP Server + SSE Proxy for Railway

Production-ready deployment of Alpaca MCP Server with Server-Sent Events (SSE) proxy, optimized for Railway and n8n integration.

Architecture

┌─────────────────────────────────────────────┐
│             Railway Container               │
│                                             │
│  ┌────────────────┐      ┌──────────────┐  │
│  │ alpaca-mcp     │      │  mcp-proxy   │  │
│  │ (HTTP backend) │◄─────┤  (SSE)       │  │
│  │ :8000          │      │  :$PORT      │  │
│  └────────────────┘      └──────────────┘  │
│                                  ▲          │
└──────────────────────────────────│──────────┘
                                   │
                         HTTPS (Railway Domain)
                                   │
                      ┌────────────┴─────────────┐
                      │                          │
                  ┌───▼────┐               ┌─────▼─────┐
                  │  n8n   │               │  Claude   │
                  │  MCP   │               │  Desktop  │
                  └────────┘               └───────────┘

Features

• Single container deployment with automatic process management
• HTTP backend (alpaca-mcp-server) + SSE frontend (mcp-proxy)
• Paper trading mode by default (safe for testing)
• Graceful shutdown with signal handling
• Health checks and automatic retries
• Railway-optimized with automatic port detection

Quick Start

Prerequisites

• Docker (for local testing)
• Railway account (for deployment)
• Alpaca API credentials (Get them here)

Local Development

1. Clone and setup

git clone <your-repo-url>
cd alpaca-mcp-server
cp .env.example .env

2. Configure credentials

Edit .env and add your Alpaca credentials:

ALPACA_API_KEY=your_key
ALPACA_SECRET_KEY=your_secret
ALPACA_PAPER_TRADE=true

3. Build and run

# Build the Docker image
docker build -t alpaca-mcp-railway .

# Run the container
docker run --rm \
  --env-file .env \
  -p 8080:8080 \
  alpaca-mcp-railway

4. Test the SSE endpoint

# Open SSE stream (should keep connection open)
curl -N http://localhost:8080/sse

# You should see SSE headers and connection established
# Press Ctrl+C to stop

5. Test with a simple request

# Example: List available tools via SSE
curl -N http://localhost:8080/sse \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

Railway Deployment

Method 1: GitHub Integration (Recommended)

1. Push to GitHub

git init
git add .
git commit -m "Initial commit: Alpaca MCP + SSE proxy"
git remote add origin <your-github-repo>
git push -u origin main

2. Deploy on Railway

• Go to Railway
• Click "New Project" → "Deploy from GitHub repo"
• Select your repository
• Railway will auto-detect the Dockerfile

3. Configure Environment Variables

In Railway dashboard, go to "Variables" and add:

ALPACA_API_KEY=your_key
ALPACA_SECRET_KEY=your_secret
ALPACA_PAPER_TRADE=true
BACKEND_PORT=8000

Note: Railway automatically provides $PORT - don't set it manually!

4. Deploy

Railway will automatically build and deploy. Check the "Deployments" tab for progress.

5. Get Your URL

• Go to "Settings" → "Networking" → "Generate Domain"
• Your SSE endpoint will be: https://<your-app>.up.railway.app/sse

Method 2: Railway CLI

# Install Railway CLI
npm install -g @railway/cli

# Login
railway login

# Create new project
railway init

# Add environment variables
railway variables set ALPACA_API_KEY=your_key
railway variables set ALPACA_SECRET_KEY=your_secret
railway variables set ALPACA_PAPER_TRADE=true
railway variables set BACKEND_PORT=8000

# Deploy
railway up

Configuration

Environment Variables

Paper vs Live Trading

Paper Trading (Recommended for testing):

ALPACA_PAPER_TRADE=true

Live Trading (Real money):

ALPACA_PAPER_TRADE=false

Important: Always test with paper trading first!

Integration with n8n

1. Install MCP Client Tool in n8n

Add the MCP Client tool to your n8n workflow.

2. Configure SSE Connection

SSE Endpoint: https://<your-app>.up.railway.app/sse
Transport: sse

3. Example n8n Workflow

{
  "nodes": [
    {
      "name": "MCP Client",
      "type": "mcp-client",
      "parameters": {
        "endpoint": "https://<your-app>.up.railway.app/sse",
        "method": "tools/list"
      }
    }
  ]
}

4. Available MCP Tools

The Alpaca MCP server provides tools for:

• Market data queries
• Account information
• Order placement and management
• Position tracking
• Historical data analysis

See Alpaca MCP documentation for full tool list.

Monitoring and Debugging

View Railway Logs

# Via Railway CLI
railway logs

# Or in Railway dashboard: "Deployments" → Select deployment → "View Logs"

Common Log Messages

Successful startup:

[INFO] Starting alpaca-mcp-server on http://0.0.0.0:8000
[INFO] Backend started with PID 42
[INFO] Waiting for backend to be ready...
[SUCCESS] Backend is ready!
[INFO] Starting mcp-proxy on 0.0.0.0:8080
[SUCCESS] mcp-proxy started with PID 43
================================================================
  Services are running!
  - Backend: http://127.0.0.1:8000
  - Frontend SSE: http://0.0.0.0:8080/sse
================================================================

Health Check

# Check if service is running
curl -I https://<your-app>.up.railway.app/sse

# Should return:
# HTTP/2 200
# content-type: text/event-stream

Troubleshooting

Issue: "Backend failed to start"

• Check that ALPACA_API_KEY and ALPACA_SECRET_KEY are set correctly
• Verify credentials at https://alpaca.markets/
• Check Railway logs for detailed error messages

Issue: "Backend failed to become ready"

• Backend may be taking longer than 60 seconds to start
• Check Railway resource limits (CPU/memory)
• Look for Python errors in logs

Issue: "Connection refused" from n8n

• Verify Railway domain is generated and accessible
• Check that Railway PORT is being used (not hardcoded)
• Test SSE endpoint with curl first

Issue: "Invalid credentials"

• Make sure you're using the correct keys for paper/live trading
• Paper keys start with PK, live keys start with AK
• Verify ALPACA_PAPER_TRADE matches your key type

Development

Project Structure

.
├── Dockerfile              # Multi-stage container build
├── package.json            # Node.js dependencies (mcp-proxy)
├── scripts/
│   └── start.sh           # Process manager script
├── .env.example           # Environment template
├── .gitignore            # Git ignore rules
└── README.md             # This file

Local Development Without Docker

# Install Node dependencies
npm install

# Install alpaca-mcp-server
pipx install alpaca-mcp-server

# Set environment variables
export ALPACA_API_KEY=your_key
export ALPACA_SECRET_KEY=your_secret
export ALPACA_PAPER_TRADE=true
export BACKEND_PORT=8000
export PORT=8080

# Run start script
bash scripts/start.sh

Running Tests

# Test backend directly
curl http://localhost:8000/

# Test SSE proxy
curl -N http://localhost:8080/sse

# Test MCP tools/list
curl -N http://localhost:8080/sse \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

Security Considerations

1. Never commit credentials: Always use environment variables
2. Use Paper Trading: Test thoroughly before switching to live
3. Railway Secrets: Store sensitive data in Railway variables, not in code
4. API Keys: Rotate keys regularly and use read-only keys when possible
5. Network Access: Consider adding authentication proxy if exposing publicly

Resources

• Alpaca MCP Server
• Alpaca Trading API
• Railway Documentation
• MCP Protocol
• n8n MCP Integration

License

MIT

Support

• Alpaca API Issues: https://alpaca.markets/support
• Railway Issues: https://help.railway.app/
• MCP Protocol: https://github.com/modelcontextprotocol

Contributing

Contributions are welcome! Please open an issue or PR.

Made with ❤️ for the n8n and MCP community