Alpaca Brokerage Interface Server

This package implements a Model Context Protocol (MCP) server specifically engineered for interfacing with the Alpaca trading platform. It empowers large language models, such as Claude, to execute financial transactions, query portfolio holdings, retrieve critical market metrics, and manage associated account elements purely through conversational directives.

Core Capabilities

• 📈 Market Intelligence - Acquire instantaneous equity quotes and historical price series data.
• 💰 Financial Oversight - Scrutinize account equity, available credit, and operational standing.
• 💼 Holding Oversight - Review existing asset positions and gauge their current performance metrics.
• 🛒 Transaction Submission - Issue market and limit trade orders directly from natural language prompts.
• 📜 Order Lifecycle Management - List, monitor the status of, and terminate pending orders.

Pre-requisites

• Execution environment running Python version 3.10 or newer.
• Valid API authentication credentials for Alpaca.
• An MCP-compatible client application (e.g., Claude for Desktop).

Deployment Instructions

1. Obtain a local copy of the source repository: bash git clone https://github.com/YOUR_USERNAME/alpaca-mcp.git cd alpaca-mcp

2. Install necessary dependencies: bash pip install mcp alpaca-py python-dotenv

3. Configure sensitive data by establishing a .env configuration file:

API_KEY_ID=your_alpaca_api_key API_SECRET_KEY=your_alpaca_secret_key

Operation Guide

Initiating the Server Module

Launch the service component with the following command:

bash python alpaca_mcp_server.py

Configuring the Client Endpoint (Claude for Desktop)

1. Launch the Claude Desktop application.
2. Navigate to the application's main configuration panel.
3. Access the 'Developer' section and select 'Edit Configuration'.
4. Integrate the service definition into your claude_desktop_config.json manifest, ensuring correct pathing and credential encapsulation:

{ "mcpServers": { "alpaca": { "command": "python", "args": [ "/path/to/alpaca_mcp_server.py" ], "env": { "API_KEY_ID": "your_alpaca_api_key", "API_SECRET_KEY": "your_alpaca_secret_key" } } } }

1. Save the modifications and reload the Claude application to apply changes.

Available Methods (Tool Signatures)

The service exposes the following callable functionalities:

• get_account_info() - Fetches current financial summaries and account operational status.
• get_positions() - Retrieves a comprehensive registry of all held assets in the portfolio.
• get_stock_quote(symbol) - Queries the most recent transactional quote for a specified ticker symbol.
• get_stock_bars(symbol, days) - Acquires historical trading data (bars) for a stock over a specified duration in days.
• get_orders(status, limit) - Generates a list of orders matching the specified state criterion, capped by a limit count.
• place_market_order(symbol, side, quantity) - Executes an instantaneous trade order.
• place_limit_order(symbol, side, quantity, limit_price) - Submits a conditional trade order at a specified price ceiling/floor.
• cancel_all_orders() - Terminates all currently pending order submissions.
• close_all_positions(cancel_orders) - Liquidates every open asset holding.

Illustrative Inquiries

Once the communication channel is established with Claude, users may pose queries such as:

• "What are my present account capital reserves and accessible trading capital?"
• "Present a summary of all securities currently held."
• "Retrieve the immediate trading price for AAPL."
• "Display the price trend data for TSLA spanning the last ten trading sessions."
• "Initiate a purchase of 5 units of MSFT utilizing the current market rate."
• "Execute a sell order for 10 units of AMZN, contingent on reaching a price floor of $130."
• "Nullify every outstanding order on my account."

Advisory Note

By default, this interface operates utilizing Alpaca's simulated (paper) trading environment. To transition to live capital deployment, modify the paper=True argument to paper=False during the initialization of the TradingClient object.

Crucial Security Disclosure

This MCP service grants comprehensive transactional authorization to the linked Alpaca brokerage account, permitting the execution of actual financial trades. It is imperative to manually audit and authorize all trade recommendations generated by the AI before execution.

Licensing Information

MIT License