XTB Platform Interface Server

This is a Model Context Protocol (MCP) instance exposing the XTB trading application programming interface (API) through the @sharplygroup/xtb-api-js software package. It facilitates interaction with your XTB brokerage account via the standardized MCP framework.

Prerequisites

• Runtime environment: Node.js (version 16 or newer recommended)
• Package manager: npm
• An active XTB trading entity registration

Deployment Steps

1. Clone the source repository: git clone [repository_url]
2. Navigate into the newly created directory: cd xtb-mcp-server
3. Install requisite project dependencies: npm install

Configuration Setup

1. Generate a local configuration file named .env within the root directory and populate it with your credentials:

   DEMO_ACCOUNT=true USER_ID=your_identifier PASSWORD=your_secret

   Crucial Note: Substitute placeholder values for your_identifier and your_secret. Adjust DEMO_ACCOUNT to false if engaging with a funded, non-simulated account.

Launching the Service

1. Compile the TypeScript source code: npm run build
2. Initiate execution of the server process: node build/index.js

Connecting via an MCP Client Interface

Connection to this broker interface can be established using any compliant MCP client, such as the official MCP Inspector utility.

1. Install the MCP Inspector globally on your system: npm install -g @modelcontextprotocol/inspector
2. Invoke the Inspector, pointing it to the running server module: npx @modelcontextprotocol/inspector node build/index.js
3. Within the Inspector's graphical interface, select the "stdio" transport modality and select the "Connect" action.

Exposed Functional Modules (Tools)

The subsequent operations are made accessible via this MCP gateway:

Account Management

• getCurrentUserData: Retrieves account base currency and associated leverage figures.
• getMarginLevel: Fetches key operational account metrics.

Computational Utilities

• getCommissionDef: Calculates the applicable commission structure and exchange rate.
  • Parameters: symbol (text identifier), volume (quantity)
• getMarginTrade: Determines the estimated margin commitment for a specified instrument and volume.
  • Parameters: symbol (text identifier), volume (quantity)
• getProfitCalculation: Estimates the potential gain/loss based on provided transactional parameters.
  • Parameters: closePrice (final rate), cmd (transaction type code), openPrice (entry rate), symbol (instrument name), volume (quantity)

Market Data Access

• getCalendar: Provides a schedule of upcoming macroeconomic events.
• getChartLastRequest: Fetches recent chart information leading up to the present moment.
  • Parameters: info (general data structure)
• getChartRangeRequest: Retrieves chart data spanning a specified temporal boundary.
  • Parameters: info (general data structure)
• getTickPrices: Returns the most recent price quotes for designated instruments, filtered by those that have changed since a given time index.
  • Parameters: level (price depth), symbols (list of instrument identifiers), timestamp (reference point in milliseconds)
• getTradingHours: Supplies the operational timings for specified financial instruments.
  • Parameters: symbols (list of instrument identifiers)

Information Dissemination

• getNews: Retrieves relevant market announcements published within a defined time window.
  • Parameters: end (stop timestamp), start (commencement timestamp)

System Status Reporting

• getServerTime: Reports the current temporal reading from the trading server clock.
• getVersion: Outputs the currently deployed API revision number.
• ping: Periodic execution of this function ensures all internal system states remain synchronized and refreshed.

Instrument Specification

• getAllSymbols: Fetches a comprehensive registry of all tradeable symbols available to the account holder.
• getSymbol: Retrieves detailed specifications for a single, named instrument.
  • Parameters: symbol (text identifier)

Transaction Handling

• getTrades: Lists the currently active positions held by the user.
  • Parameters: openedOnly (boolean flag)
• getTradeRecords: Fetches status details for a specified collection of order identifiers.
  • Parameters: orders (array of numerical order IDs)
• getTradesHistory: Retrieves records of all trades that were finalized within a specified historical period.
  • Parameters: end (closing timestamp), start (opening timestamp)
• getTradeStatus: Inquires about the current processing state of a specific transaction.
  • Parameters: order (numerical order ID)

Trading Execution

• tradeTransaction: Initiates a new transactional request (e.g., opening/closing a position).
  • Parameters: tradeTransInfo (detailed transaction payload)
• tradeTransactionStatus: Queries the real-time status of a pending transaction.
  • Parameters: order (numerical order ID)

Direct Command Invocation

• executeCommand: Allows for direct execution of arbitrary commands supported by the underlying server component.
  • Parameters: command (string representing the command to run)

Predefined Inquiry Sequences (Prompts)

The following abstracted inputs are available for simplified data retrieval:

• getAccountDataPrompt: Triggers retrieval of the current account summary information.
• getSymbolInfoPrompt: Facilitates querying parameters for a designated trading instrument.
  • Parameters: symbol (text identifier)

Legal Notice

This MCP server implementation is provided strictly as an illustrative example. Users assume all liability for its deployment. Thoroughly comprehend the XTB API documentation and associated market risks before connecting this service to any live, funded trading account.