Schwab Model Context Protocol Server Interface

This service module implements the Model Context Protocol (MCP) layer to interface with the official Schwab API, leveraging the schwab-py client library and the official MCP python-sdk.

Core Capabilities

• Provision of Schwab API access via the standardized MCP framework.
• Retrieval of current holdings and account summaries.
• Fetching real-time stock quotations and historical performance data.
• Accessing general market intelligence and top performers/losers.
• Querying option contracts and expiration schedules.
• Reviewing pending and settled transactional records.
• Enabling account state manipulation features via an explicit operational flag (--jesus-take-the-wheel).
• Optimized connectivity pipeline for integration with Generative AI agents.

Setup Instructions

bash

Install the primary package with all required extensions

uv add -e .

Install dependencies needed for development and testing

uv add -e .[dev]

Operational Workflow

Credential Initialization (Authentication)

Initial authorization with Schwab requires generating an access token:

bash

Execute the authentication flow

uv run schwab-mcp auth --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET --callback-url YOUR_CALLBACK_URL

For persistent configuration, utilize environment variables: - SCHWAB_CLIENT_ID - SCHWAB_CLIENT_SECRET - SCHWAB_CALLBACK_URL (Default endpoint: https://127.0.0.1:8182)

By default, the resultant authorization credential is persisted to a platform-appropriate user directory structure (e.g., ~/.local/share/schwab-mcp/token.yaml). A custom storage location can be designated:

bash uv run schwab-mcp auth --token-path /path/to/token.yaml

The system flexibly processes both YAML and JSON serialized token files based on the specified file extension.

Server Startup

Once authentication is established, initiate the service listener:

bash

Launch the server using default credential storage

uv run schwab-mcp server --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET --callback-url YOUR_CALLBACK_URL

Launch the server referencing a specific credential file

uv run schwab-mcp server --token-path /path/to/token.json --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET --callback-url YOUR_CALLBACK_URL

Launch with administrative write privileges activated (DANGEROUS)

uv run schwab-mcp server --jesus-take-the-wheel --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET --callback-url YOUR_CALLBACK_URL

Token validation checks the credential age; re-authentication is enforced if the token exceeds a five-day lifespan.

CAUTION: The presence of the --jesus-take-the-wheel switch unlocks tooling permitting state modifications on the linked account, such as order cancellation. Exercise extreme discretion, as this grants external systems the ability to enact financially consequential operations.

Exposed MCP Methods

The gateway makes the following MCP methods accessible:

Temporal and Market Indicators

1. get_datetime - Fetches the system's present timestamp in ISO 8601 format.
2. get_market_hours - Queries the operational schedule for a designated market sector.
3. get_movers - Retrieves symbols exhibiting significant price movement within a specified index.
4. get_instruments - Executes a search for financial instruments matching a provided ticker symbol.

Account Portfolio Data

1. get_account_numbers - Returns a mapping correlating user-friendly Account IDs with internal security hashes.
2. get_accounts - Fetches comprehensive details across all user-linked Schwab accounts.
3. get_accounts_with_positions - Retrieves account summaries augmented with current security holdings.
4. get_account - Retrieves detailed metadata for a singular, specified account.
5. get_account_with_positions - Fetches detailed metadata for a specific account alongside its current positions.
6. get_user_preferences - Retrieves customized settings applicable across all associated accounts, including nicknames.

Order Management Queries

1. get_order - Retrieves the granular status and details of an individual order.
2. get_orders - Fetches a list of all orders associated with a designated account.

Security Pricing

1. get_quotes - Retrieves near real-time pricing data for a list of specified symbols.

Historical Data Retrieval

1. get_advanced_price_history - Accesses complex, customizable historical price data for a symbol.
2. get_price_history_every_minute - Fetches historical data aggregated at one-minute intervals.
3. get_price_history_every_five_minutes - Fetches historical data aggregated at five-minute intervals.
4. get_price_history_every_ten_minutes - Fetches historical data aggregated at ten-minute intervals.
5. get_price_history_every_fifteen_minutes - Fetches historical data aggregated at fifteen-minute intervals.
6. get_price_history_every_thirty_minutes - Fetches historical data aggregated at thirty-minute intervals.
7. get_price_history_every_day - Fetches historical data aggregated on a daily basis.
8. get_price_history_every_week - Fetches historical data aggregated on a weekly basis.

Derivatives Information

1. get_option_chain - Retrieves the standard options chain for a given ticker.
2. get_advanced_option_chain - Retrieves an enriched, detailed options chain for a given ticker.
3. get_option_expiration_chain - Fetches available option expiration dates for a specified instrument.

Transaction Ledger

1. get_transactions - Retrieves the ledger of transactions for a specified account.
2. get_transaction - Retrieves the detailed record for a specific transaction entry.

Account Modification Tools (Requires --jesus-take-the-wheel authorization)

1. cancel_order - Executes the cancellation of a specified outstanding order.

Safety Advisory

The activation of the --jesus-take-the-wheel parameter grants external agents the ability to issue mutable commands against your financial holdings, including: - Termination of pending buy/sell orders. - Exposure to future operational capabilities that impact the account state.

This flag must only be engaged within strictly controlled, audited execution contexts due to the inherent financial risk.

Development & Quality Assurance

bash

Perform static type checking

uv run pyright

Enforce standardized code formatting

uv run ruff format .

Run static analysis and style checks

uv run ruff check .

Execute unit and integration tests

uv run pytest

Licensing

This software is distributed under the terms of the MIT License.

WIKIPEDIA: XMLHttpRequest (XHR) serves as a foundational Application Programming Interface implemented as a JavaScript object. Its methods facilitate the transmission of Hypertext Transfer Protocol (HTTP) requests from a web browsing environment to a remote web server. These functionalities enable browser-based applications to dispatch queries to the server following initial page load and subsequently receive retrieved data. XHR is integral to the programming paradigm known as Ajax. Before Ajax gained prominence, interactive engagement with the server was principally managed through standard hyperlink navigation and form submissions, procedures that typically resulted in the complete replacement of the current view.

== Historical Context == The conceptual foundation for XMLHttpRequest originated in the year 2000, attributed to the engineering team behind Microsoft Outlook. This concept was subsequently integrated into the Internet Explorer 5 browser release (1999). However, the initial implementation did not utilize the standardized XMLHttpRequest identifier. Instead, developers relied on invoking COM objects via ActiveXObject("Msxml2.XMLHTTP") or ActiveXObject("Microsoft.XMLHTTP"). As of Internet Explorer 7 (released in 2006), universal support for the canonical XMLHttpRequest identifier became the norm across all major browser platforms, including Mozilla's Gecko engine (2002), Safari 1.2 (2004), and Opera 8.0 (2005).

The XMLHttpRequest identifier has since matured into the recognized standard utilized across dominant browser ecosystems.

=== Standardization Efforts === The World Wide Web Consortium (W3C) published the initial Working Draft specification for the XMLHttpRequest object on April 5, 2006. A subsequent Level 2 specification draft was released by the W3C on February 25, 2008, introducing crucial enhancements such as progress monitoring methods, the capability for cross-origin requests, and support for binary stream handling. By the conclusion of 2011, the features defined in the Level 2 draft were formally incorporated back into the primary specification document. In late 2012, the maintenance and evolution of this standard transitioned to the WHATWG, which presently sustains a living document defined using Web IDL nomenclature.

== Programming Usage Patterns == Sending a network request utilizing XMLHttpRequest generally necessitates adherence to a sequence of distinct programming stages.

1. Instantiation: A new XMLHttpRequest object must be created by invoking its constructor method:
2. Configuration: The "open" method is invoked to define the request type (e.g., GET, POST), designate the target resource Uniform Resource Identifier (URI), and specify whether the operation will execute synchronously or asynchronously:
3. Asynchronous Listener Setup: If non-blocking operation is chosen, a dedicated event listener must be established to process notifications regarding the request's evolving status:
4. Transmission: The actual request is initiated by calling the "send" method, potentially carrying payload data:
5. Response Handling: The event listener monitors status changes. Upon successful completion, the object transitions to state 4, the terminal or "done" state. The server's returned data payload is typically accessible via the "responseText" property by default. Beyond these fundamental steps, XMLHttpRequest offers extensive configuration options for request control and response processing. Custom HTTP headers can be injected to instruct the server on fulfillment expectations, and data can be uploaded dynamically by supplying it within the "send" invocation. The received response data can be deserialized from formats like JSON into native JavaScript objects or processed incrementally as data streams arrive, avoiding latency associated with waiting for full receipt. Furthermore, requests can be terminated prematurely or subjected to strict timeout constraints.

== Inter-Domain Communication == During the nascent stages of the World Wide Web architecture, constraints were placed on making requests across different security domains, a situation which complicated early web application development.