Alpaca MCP Gold Standard

A server for interacting with the Alpaca trading API. Requires API credentials via environment variables.

A comprehensive implementation of the definitive MCP (Model Context Protocol) server architecture for professional trading operations, achieving 100% compliance with gold standard patterns documented in the Quick Data MCP reference architecture.

This implementation represents thedefinitive referencefor professional MCP development, implementing all 7 core architectural patterns with 50+ tools spanning trading operations, advanced analytics, and universal data analysis capabilities.

- 31 MCP Tools: Complete coverage of trading operations
- 11 Resource Mirrors: Universal client compatibility
- 4 Context Prompts: Intelligent conversation guidance
- 7/7 Architecture Patterns: 100% gold standard compliance
- 50+ Total Capabilities: Comprehensive trading platform
- 91 Real API Tests: 100% pass rate with actual Alpaca API integration

Automatically classifies stocks and positions with intelligent role assignment:

- Growth Candidates: Stocks with positive momentum indicators
- Volatile Assets: High-volatility positions requiring active monitoring
- Income Generators: Dividend-paying or stable return positions
- Hedge Instruments: Risk management and portfolio protection assets
- Speculative Plays: High-risk, high-reward opportunities

Universal compatibility with ANY MCP client:

- 11 mirror tools provide identical functionality to resources
- Zero maintenance overhead through function wrapping
- Seamless fallback for tool-only clients
- Future-proof migration path

Conversation starters that reference your actual portfolio:

- portfolio_first_look- Analyzes your specific holdings
- trading_strategy_workshop- Customized to your portfolio composition
- market_analysis_session- Focused on your tracked symbols
- list_mcp_capabilities- Complete feature guide

Execute custom analysis with subprocess isolation:

- Trading Strategies: Run custom algorithms with portfolio context
- Portfolio Optimization: Advanced optimization with risk parameters
- Risk Analysis: Custom risk metrics and calculations
- Universal Analytics: Works with ANY dataset structure
- 30-second timeout protection with comprehensive error handling

- Portfolio Health Assessment: 100-point scoring system

- Diversification analysis
- Risk concentration metrics
- Performance balance evaluation
- Actionable recommendations with specific tools

- Identify over-correlated positions
- Diversification scoring
- Risk insights and recommendations

Beyond trading - works with ANY structured data:

- Auto-discovers column types and relationships
- Generic correlation and segmentation tools
- Adaptive visualization capabilities
- Cross-dataset integration patterns

{ "status": "error", "message": "Human-readable error description", "error_type": "ExceptionType", "metadata": {"context": "additional_info"} }

- Python 3.12+
- uv package manager
- Alpaca trading account (paper trading supported)

# Clone and setup git clone <repository> cd alpaca-mcp-gold-standard # Install dependencies uv sync # Configure environment cp .env.example .env # Edit .env with your Alpaca API credentials

# Development mode uv run python main.py # Debug mode with verbose logging LOG_LEVEL=DEBUG uv run python main.py # Production mode with Docker docker build -t alpaca-mcp-gold . docker run -p 8000:8000 --env-file .env alpaca-mcp-gold

# Run all tests with coverage uv run pytest tests/ -v --cov=src --cov-report=term-missing # Test specific gold standard patterns uv run pytest tests/test_resource_mirrors.py -v # Resource mirror pattern uv run pytest tests/test_state_management.py -v # State management uv run pytest tests/test_integration.py -v # Full workflows

{ "mcpServers": { "alpaca-trading-gold": { "command": "/path/to/uv", "args": [ "--directory", "/absolute/path/to/alpaca-mcp-gold-standard", "run", "python", "main.py" ], "env": { "LOG_LEVEL": "INFO" } } } }

Account & Portfolio Management (4 tools)

- get_account_info_tool()- Real-time account status with portfolio insights
- get_positions_tool()- Holdings with adaptive role classification
- get_open_position_tool(symbol)- Specific position details
- get_portfolio_summary_tool()- Comprehensive analysis with AI suggestions

- get_stock_quote_tool(symbol)- Real-time quotes with spread analysis
- get_stock_trade_tool(symbol)- Latest trade information
- get_stock_snapshot_tool(symbols)- Complete market data with volatility
- get_historical_bars_tool(symbol, timeframe)- Historical OHLCV data

- place_market_order_tool(symbol, side, quantity)- Immediate execution
- place_limit_order_tool(symbol, side, quantity, price)- Price targeting
- place_stop_loss_order_tool(symbol, side, quantity, stop_price)- Risk management
- get_orders_tool(status, limit)- Order history and tracking
- cancel_order_tool(order_id)- Order cancellation

- execute_custom_trading_strategy_tool(code, symbols)- Run custom algorithms
- execute_portfolio_optimization_strategy_tool(code, risk_tolerance)- Optimize holdings
- execute_risk_analysis_strategy_tool(code, benchmarks)- Risk analytics

- generate_portfolio_health_assessment_tool()- 100-point health scoring
- generate_advanced_market_correlation_analysis_tool(symbols)- Correlation matrices

- execute_custom_analytics_code_tool(dataset, code)- Any dataset analysis
- create_sample_dataset_from_portfolio_tool()- Convert portfolio to dataset

Every resource has a corresponding tool for universal compatibility:

- resource_account_info_tool()→trading://account/info
- resource_portfolio_summary_tool()→trading://portfolio/summary
- And 9 more mirror tools...

- clear_portfolio_state_tool()- Reset state for testing

src/mcp_server/ ├── config/ # Environment-based configuration │ ├── settings.py # Pydantic settings management │ └── simple_settings.py # Simplified config loader ├── models/ # Core business logic │ ├── schemas.py # Entity classification & state management │ └── alpaca_clients.py # Singleton API client management ├── tools/ # 31 MCP tools by category │ ├── account_tools.py # Account operations │ ├── market_data_tools.py # Market data access │ ├── order_management_tools.py # Trading operations │ ├── custom_strategy_execution.py # Safe code execution │ ├── advanced_analysis_tools.py # Portfolio analytics │ ├── execute_custom_analytics_code_tool.py # Universal analytics │ └── resource_mirror_tools.py # Compatibility layer ├── resources/ # URI-based data access │ └── trading_resources.py # trading:// scheme handlers ├── prompts/ # Context-aware conversations │ └── trading_prompts.py # 4 adaptive prompt generators └── server.py # FastMCP registration (31 tools)

tests/ ├── conftest.py # Mock Alpaca API & fixtures ├── test_account_tools.py # Account operation tests ├── test_market_data_tools.py # Market data tests ├── test_order_management_tools.py # Order operation tests ├── test_resources.py # Resource URI tests ├── test_resource_mirrors.py # Mirror consistency validation ├── test_state_management.py # Memory & state tests └── test_integration.py # Complete workflow tests

- Automatic state cleanup between tests
- Mock Alpaca API with realistic responses
- Helper functions for response validation
- Memory usage tracking

Every stock/position is intelligently classified:

entity = EntityInfo( symbol="AAPL", suggested_role=EntityRole.GROWTH_CANDIDATE, characteristics=["high_momentum", "tech_sector", "large_cap"], confidence_score=0.85 )

# Automatic cleanup and tracking StateManager.add_symbol("AAPL", entity_info) memory_usage = StateManager.get_memory_usage() # Returns MB used StateManager.clear_all() # Clean slate

# Safe execution with timeout async def execute_custom_code(code: str) -> str: process = await asyncio.create_subprocess_exec( 'uv', 'run', '--with', 'pandas', '--with', 'numpy', 'python', '-c', execution_code, stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.STDOUT ) stdout, _ = await asyncio.wait_for(process.communicate(), timeout=30)

# Context-aware suggestions based on actual holdings "Your portfolio shows high concentration in tech stocks (65%). Consider diversifying with healthcare or consumer staples for better risk balance. Use get_stock_snapshot('JNJ,PG,KO') to research defensive positions."

- Response Times: Average <100ms for data operations
- Memory Usage: ~50MB idle, ~200MB with full portfolio loaded
- Subprocess Timeout: 30-second protection for custom code
- Health Monitoring: Continuous Alpaca API connection checks
- State Tracking: Real-time memory usage monitoring
- Create function in appropriatetools/category_tools.py
- Follow the standard response format:

async def your_new_tool(param: str) -> Dict[str, Any]: try: # Implementation return { "status": "success", "data": result_data, "metadata": {"operation": "your_new_tool"} } except Exception as e: return { "status": "error", "message": str(e), "error_type": type(e).__name__ }

# Format code uv run black src/ tests/ # Lint code uv run ruff check src/ tests/ # Type checking uv run mypy src/ # Run all quality checks uv run black src/ tests/ && uv run ruff check src/ tests/ && uv run mypy src/

- Credential Management: Environment variables only
- Input Validation: Pydantic models for all inputs
- Error Sanitization: No credentials in error messages
- Subprocess Isolation: Untrusted code runs in sandbox
- API Rate Limiting: Built-in Alpaca rate limit handling

- README.md: This comprehensive guide
- CLAUDE.md: Guidance for Claude Code development
- ai_docs/: AI-optimized references

- alpaca_py_sdk_reference.md- Alpaca SDK guide
- mcp_server_sdk_reference.md- MCP patterns guide

- architecture_overview.md- Gold standard patterns
- custom_analytic_code.md- Subprocess design
- poc_init_generic.md- Universal patterns
- resource_workaround.md- Mirror pattern

- Parallel implementation patterns
- Validation frameworks

# Build production image docker build -t alpaca-mcp-gold . # Run with environment file docker run -d \ --name alpaca-mcp \ -p 8000:8000 \ --env-file .env \ --restart unless-stopped \ alpaca-mcp-gold

# Required ALPACA_API_KEY=your_api_key ALPACA_SECRET_KEY=your_secret_key # Optional ALPACA_PAPER_TRADE=True # Use paper trading (recommended) LOG_LEVEL=INFO # Logging verbosity MCP_SERVER_NAME=alpaca-trading-gold

This project serves as the gold standard reference for MCP development. When contributing:
- Follow Architecture Patterns: Maintain all 7 gold standard patterns
- Comprehensive Testing: Minimum 80% coverage for new code
- Documentation: Update relevant docs for new features
- Consistency: Match existing code style and patterns
- Review Checklist:

- Tests pass with coverage
- Resource mirrors updated if needed
- Error handling follows standard format
- Documentation updated
- Type hints included

This is not just another MCP server - it's amasterclass in software architecture:
- Reference Implementation: Demonstrates every MCP best practice
- Production Ready: Comprehensive error handling, monitoring, and testing
- Universal Patterns: Techniques applicable to ANY domain
- Educational Value: Learn professional MCP development patterns
- Extensible Foundation: Easy to adapt for other use cases

The architecture is designed for expansion:

- Real-time WebSocket market data streaming
- Advanced portfolio optimization algorithms
- Multi-account management support
- Trading strategy backtesting framework
- Integration with additional brokers
- Machine learning-powered insights

This project is licensed under the same terms as the original Alpaca MCP server.

Built upon the foundation of the original Alpaca MCP server, implementing the comprehensive best practices documented in the parent repository's analysis of gold standard MCP patterns. Special thanks to the MCP and Alpaca communities for their excellent documentation and tools.

This is the definitive reference implementation for professional MCP development.Whether you're building trading systems, data analytics platforms, or any other MCP-powered application, this codebase demonstrates the patterns and practices that lead to production-ready, maintainable, and extensible systems.

Interact with the Alpaca trading API for stock trading, market data, and account management.

Interact with Alpaca's Trading API for stock trading, portfolio management, and real-time market data.

Provides seamless access to the Binance exchange API. Requires Binance API credentials to be configured.

Interact with the Binance API to view portfolios, convert tokens, and execute trades with minimal market impact.

Access the Binance Futures API for trading, account management, and market data.

Interact with the Invertir Online (IOL) API to manage investments and access market data.

An MCP server for interacting with the T-Invest API, providing access to investment and financial data.

MCP server for Tradernet/Freedom24 trading API — portfolio, orders, quotes, alerts and more

The Capital.com MCP Server lets your AI assistant talk to your trading account directly. Market data, position checks, trade previews – all in plain language, without leaving your AI tool.

US/HK markets — 110 tools: real-time quotes, options, orders, fundamentals, alerts, DCA & portfolio