Getting Started

This guide will help you set up StockBud and connect it to your AI assistant.

Prerequisites

Python 3.10+

Required for running the MCP server

Alpaca Account

Paper or live brokerage account for trading

AI Assistant

Claude Desktop, Cursor, or MCP-compatible client

Installation

Clone the Repository

git clone https://github.com/neverpeak/mcp-server-stockbud.io
cd mcp-server-stockbud.io

Install Dependencies

We use uv for fast Python dependency management:

uv venv
uv pip install -r requirements.txt

Don't have uv? Install with pip install uv or brew install uv

Configure Environment

Copy the sample environment file:

cp env.v2.sample .env

Edit .env with your API keys:

# Alpaca API (get from alpaca.markets)
ALPACA_API_KEY=your_api_key
ALPACA_SECRET_KEY=your_secret_key
ALPACA_BASE_URL=https://paper-api.alpaca.markets
 
# Optional: OpenAI for AI features
OPENAI_API_KEY=your_openai_key

Start the MCP Server

uv run python scripts/start/stockbud_main.py

You should see:

🚀 StockBud MCP Server starting...
✅ Connected to Alpaca (paper trading)
📡 MCP server ready on stdio

Connect to Claude Desktop

Add this to your Claude Desktop config (~/.config/claude/claude_desktop_config.json on macOS/Linux):

{
  "mcpServers": {
    "stockbud": {
      "command": "uv",
      "args": ["run", "python", "scripts/start/stockbud_main.py"],
      "cwd": "/path/to/mcp-server-stockbud.io"
    }
  }
}

Replace /path/to/mcp-server-stockbud.io with your actual installation path.

Test the Connection

In Claude Desktop, try asking:

"Show me my Alpaca portfolio"

You should see your current positions and account balance.

Demo Mode

Don't have an Alpaca account yet? Try demo mode with mock data:

STOCKBUD_DEMO_MODE=1 uv run python scripts/start/stockbud_main.py

Next Steps

Quick Start

5-minute setup guide

API Reference

Explore MCP tools and endpoints

Configuration

Environment variables and options