2498 Alpaca Mcp Setup Fdfb5774

# Alpaca MCP Server Setup Guide

This guide explains how to set up and configure the Alpaca MCP (Model Context Protocol) Server for use with the Portfolio Manager skill.

## What is Alpaca MCP Server?

The Alpaca MCP Server is a Model Context Protocol server that provides Claude with access to your Alpaca brokerage account data through a standardized interface. This allows the Portfolio Manager skill to fetch real-time portfolio positions, account information, and transaction history directly from your Alpaca account.

## Prerequisites

### 1. Alpaca Account

You need an Alpaca brokerage account (paper trading or live):

- **Sign up:** https://alpaca.markets/
- **Paper Trading:** Free, uses simulated money (recommended for testing)
- **Live Trading:** Real money account (requires funding)

### 2. Alpaca API Keys

Generate API keys from your Alpaca dashboard:

**For Paper Trading:**
1. Log into Alpaca dashboard: https://app.alpaca.markets/
2. Navigate to "Paper Trading" account
3. Go to "Your API Keys" section
4. Click "Generate New Key"
5. Save your:
   - **API Key ID** (public key)
   - **Secret Key** (private key - only shown once!)

**For Live Trading:**
1. Log into Alpaca dashboard
2. Navigate to "Live Trading" account
3. Go to "Your API Keys" section
4. Click "Generate New Key"
5. Save your API credentials

⚠️ **Security Note:** Never share your Secret Key or commit it to version control. Treat it like a password.

## Installation

### Option 1: Using MCP Server (Recommended for Claude Desktop/Web)

**Step 1: Install Alpaca MCP Server**

The Alpaca MCP server may be available through Claude's MCP marketplace or as a standalone package.

Check if available in your Claude environment:
```bash
# List available MCP servers
claude mcp list
```

If not installed, follow Anthropic's MCP server installation guide for your platform.

**Step 2: Configure API Keys**

Set environment variables with your Alpaca credentials:

**On macOS/Linux:**
```bash
# For Paper Trading
export ALPACA_API_KEY="your_api_key_id"
export ALPACA_SECRET_KEY="your_secret_key"
export ALPACA_PAPER=true

# For Live Trading
export ALPACA_API_KEY="your_api_key_id"
export ALPACA_SECRET_KEY="your_secret_key"
export ALPACA_PAPER=false
```

Add to `~/.bashrc` or `~/.zshrc` to persist across sessions:
```bash
echo 'export ALPACA_API_KEY="your_api_key_id"' >> ~/.bashrc
echo 'export ALPACA_SECRET_KEY="your_secret_key"' >> ~/.bashrc
echo 'export ALPACA_PAPER=true' >> ~/.bashrc
source ~/.bashrc
```

**On Windows (PowerShell):**
```powershell
# For Paper Trading
$env:ALPACA_API_KEY="your_api_key_id"
$env:ALPACA_SECRET_KEY="your_secret_key"
$env:ALPACA_PAPER="true"

# For Live Trading
$env:ALPACA_API_KEY="your_api_key_id"
$env:ALPACA_SECRET_KEY="your_secret_key"
$env:ALPACA_PAPER="false"
```

To persist environment variables on Windows:
```powershell
[System.Environment]::SetEnvironmentVariable('ALPACA_API_KEY', 'your_api_key_id', 'User')
[System.Environment]::SetEnvironmentVariable('ALPACA_SECRET_KEY', 'your_secret_key', 'User')
[System.Environment]::SetEnvironmentVariable('ALPACA_PAPER', 'true', 'User')
```

**Step 3: Start MCP Server**

The MCP server should start automatically when Claude launches. Verify connection:
```bash
# Check MCP server status (if CLI available)
claude mcp status
```

### Option 2: Direct API Integration (Alternative)

If MCP server is unavailable, the skill can fall back to direct Alpaca API integration using Python:

**Step 1: Install Alpaca Python SDK**
```bash
pip install alpaca-trade-api
```

**Step 2: Create Configuration File**

Create `~/.alpaca/config.ini`:
```ini
[alpaca]
api_key_id = your_api_key_id
secret_key = your_secret_key
base_url = https://paper-api.alpaca.markets  # For paper trading
# base_url = https://api.alpaca.markets     # For live trading
```

Set proper permissions:
```bash
chmod 600 ~/.alpaca/config.ini
```

**Step 3: Test Connection**

Use the provided test script:
```bash
python3 portfolio-manager/scripts/test_alpaca_connection.py
```

Expected output:
```
✓ Successfully connected to Alpaca API
Account Status: ACTIVE
Equity: $100,000.00
Cash: $50,000.00
Buying Power: $200,000.00
Positions: 5
```

## Available MCP Tools

Once configured, the Portfolio Manager skill can use these Alpaca MCP tools:

### `mcp__alpaca__get_account_info`
Fetches account summary:
- Total equity (portfolio value)
- Cash balance
- Buying power
- Account status
- Day trading buying power (if applicable)

### `mcp__alpaca__get_positions`
Retrieves all open positions:
- Symbol ticker
- Quantity (shares)
- Average entry price (cost basis)
- Current market price
- Current market value
- Unrealized P&L ($ and %)
- Today's P&L

### `mcp__alpaca__get_portfolio_history`
Gets historical portfolio performance:
- Equity time series
- Profit/loss time series
- Timeframes: 1D, 1W, 1M, 3M, 1Y, All

### `mcp__alpaca__get_orders`
Lists orders (open, filled, cancelled):
- Order ID
- Symbol
- Quantity
- Order type (market, limit, stop, etc.)
- Status
- Fill price (if filled)
- Timestamps

### `mcp__alpaca__get_activities`
Retrieves account activities:
- Trades (fills)
- Dividend payments
- Stock splits
- Journal entries

## Verification and Testing

### Test 1: Account Connection

Ask Claude to fetch account info:
```
"Can you get my Alpaca account information?"
```

Expected response should include your equity, cash, and buying power.

### Test 2: Portfolio Positions

Request current positions:
```
"What positions do I have in my portfolio?"
```

Expected response should list all holdings with quantities and values.

### Test 3: Portfolio Analysis

Trigger the Portfolio Manager skill:
```
"Analyze my portfolio"
```

The skill should:
1. Fetch positions via MCP
2. Gather additional market data
3. Perform comprehensive analysis
4. Generate detailed report

## Troubleshooting

### Error: "Alpaca MCP Server not connected"

**Possible causes:**
1. MCP server not running
2. API keys not configured
3. API keys invalid or expired

**Solutions:**
1. Restart Claude to reinitialize MCP servers
2. Verify environment variables are set: `echo $ALPACA_API_KEY`
3. Check API keys in Alpaca dashboard (regenerate if needed)
4. Verify account status (ensure not suspended)

### Error: "Invalid API credentials"

**Possible causes:**
1. Wrong API keys
2. Using live keys with paper mode (or vice versa)
3. API keys revoked

**Solutions:**
1. Double-check API Key ID and Secret Key (no extra spaces)
2. Verify `ALPACA_PAPER` setting matches your API keys
3. Regenerate API keys in Alpaca dashboard
4. Ensure you're using the correct account (paper vs live)

### Error: "Forbidden - insufficient permissions"

**Possible causes:**
1. API keys have restricted permissions
2. Account not approved for trading

**Solutions:**
1. Regenerate API keys with full permissions
2. Check Alpaca dashboard for account status
3. For live accounts, ensure account approval is complete

### Error: "No positions found"

**Possible causes:**
1. Portfolio is actually empty
2. Wrong account selected (paper vs live)
3. API returning stale data

**Solutions:**
1. Verify positions exist in Alpaca dashboard
2. Confirm `ALPACA_PAPER` setting matches intended account
3. Try refreshing: ask Claude to fetch positions again
4. Check Alpaca API status page: https://status.alpaca.markets/

### MCP Server Not Responding

**Solutions:**
1. Restart Claude application
2. Check MCP server logs (if available)
3. Verify network connectivity
4. Fall back to direct API integration (Option 2)

## Security Best Practices

### 1. Use Paper Trading for Testing
Always test with paper trading account first. Never risk real money until thoroughly tested.

### 2. Protect API Keys
- Never commit API keys to GitHub or version control
- Use environment variables, not hardcoded values
- Set file permissions: `chmod 600` for config files
- Rotate keys periodically (every 90 days)

### 3. Use Read-Only Keys (If Available)
For portfolio analysis only, use read-only API keys if Alpaca supports them. This prevents accidental trading.

### 4. Monitor API Usage
- Check Alpaca dashboard for API call logs
- Review account activities regularly
- Set up alerts for unusual activity

### 5. Separate Paper and Live Environments
- Use different environment variable prefixes
- Never mix paper and live credentials
- Document which keys are which

## API Rate Limits

Alpaca imposes rate limits on API calls:

**Free Tier:**
- 200 requests per minute
- Data delayed by 15 minutes (for free market data)

**Paid Tier (Alpaca Markets Data subscription):**
- Higher rate limits
- Real-time data

**Best Practices:**
- Portfolio Manager skill includes built-in rate limiting
- Avoid running analysis more than once per minute
- For frequent monitoring, consider caching results

## Alternative: Manual Data Entry

If Alpaca integration is unavailable, Portfolio Manager can accept manually entered portfolio data:

**CSV Format:**
```csv
symbol,quantity,cost_basis,current_price
AAPL,100,150.00,175.50
MSFT,50,280.00,310.25
GOOGL,25,2500.00,2750.00
```

**Usage:**
1. Export positions from your broker as CSV
2. Provide file to Claude: "Analyze my portfolio using this CSV file"
3. Skill will parse data and perform analysis

**Limitations:**
- No real-time updates
- No historical performance data
- Manual updates required

## Additional Resources

**Alpaca Documentation:**
- API docs: https://alpaca.markets/docs/
- Python SDK: https://github.com/alpacahq/alpaca-trade-api-python
- API reference: https://alpaca.markets/docs/api-references/trading-api/

**MCP Protocol:**
- Anthropic MCP docs: https://docs.anthropic.com/claude/docs/model-context-protocol
- MCP specification: https://github.com/anthropics/mcp

**Support:**
- Alpaca support: support@alpaca.markets
- Alpaca community: https://forum.alpaca.markets/
- API status: https://status.alpaca.markets/