Forex-GPT MCP Server

Save your OANDA API Key and Account ID securely. These are required before you can trade.

Remove/Delete your stored OANDA API Key and Account ID. Use this if you want to clear your credentials or switch accounts.

Modify an existing trade's Stop Loss and Take Profit. You can use absolute prices OR relative distances. Only provided fields will be updated. Args: trade_id: The ID of the open trade to modify. take_profit: New ABSOLUTE price. stop_loss: New ABSOLUTE price. take_profit_distance: New RELATIVE distance (e.g. 0.0050). stop_loss_distance: New RELATIVE distance (e.g. 0.0020).

Place a Market Order. units: Positive for Buy, Negative for Sell take_profit: ABSOLUTE PRICE (e.g. 1.1250). stop_loss: ABSOLUTE PRICE (e.g. 1.1100). take_profit_distance: RELATIVE PIPS (e.g. 0.0050). Use this OR absolute price. stop_loss_distance: RELATIVE PIPS (e.g. 0.0020). Use this OR absolute price. trailing_stop_distance: RELATIVE DISTANCE for trailing stop (e.g. 0.0020). guaranteed_stop_loss: True to use GSLO (Premium, requires specific SL distance rule).

Place a Limit Order. price: The limit price to trigger the order. take_profit: ABSOLUTE PRICE (e.g. 1.1250). stop_loss: ABSOLUTE PRICE (e.g. 1.1100). take_profit_distance: RELATIVE PIPS (e.g. 0.0050). stop_loss_distance: RELATIVE PIPS (e.g. 0.0020). trailing_stop_distance: RELATIVE DISTANCE for trailing stop. guaranteed_stop_loss: True for GSLO. expiry: ISO 8601 string (e.g. "2023-12-31T23:59:00Z"). Defaults to GTC if omitted.

Place a Stop Order (Momentum/Breakout Entry). Use this to Buy ABOVE market price or Sell BELOW market price. Args: instrument: Asset symbol (e.g. 'EUR_USD') units: Positive for Buy, Negative for Sell price: The STOP price to trigger the order. expiry: ISO 8601 string (e.g. "2023-12-31T23:59:00Z"). Defaults to GTC if omitted. take_profit: ABSOLUTE PRICE. stop_loss: ABSOLUTE PRICE. take_profit_distance: RELATIVE DISTANCE (e.g. 0.0050). stop_loss_distance: RELATIVE DISTANCE (e.g. 0.0020). trailing_stop_distance: RELATIVE DISTANCE for trailing stop. guaranteed_stop_loss: True for GSLO.

Cancel a pending (unfilled) Limit or Stop order. Args: order_id: The OANDA ID of the order to cancel.

Replace (Modify) an existing pending order. Basically cancels the old one and places a new one atomically. Args: order_id: ID of the order to replace. type: 'LIMIT' or 'STOP'. (All other args same as placement tools)

List open trades.

List open positions (Net Exposure per instrument). Useful to see total Long/Short units and P&L per pair.

Get account transaction history (e.g. closed trades, order fills). Useful for finding past trades, reporting, or auditing. Args: from_time: Start time (RFC3339 format, e.g. "2023-05-01T00:00:00Z"). to_time: End time (RFC3339). type_filter: Comma-separated types (e.g. "ORDER_FILL,TRADE_CLOSE"). To see closed trades, use "TRADE_CLOSE".

Get full details of a specific trade (Open or Closed). Useful to investigate a trade that disappeared or to see its full history.

Get OANDA order history (FILLED, CANCELLED, TRIGGERED, etc.). state: "ALL", "PENDING", "FILLED", "TRIGGERED", "CANCELLED". count: Max 500.

List all PENDING orders (Limits, Stops, Entry Orders). These are orders waiting to be filled.

Get trading account summary (balance, margin).

Close a specific trade (fully or partially).

Close position for an instrument.

Get trading hours for instruments. Use for session planning or bulk data fetch. Args: instrument: Specific instrument (e.g., "EUR_USD", "US30_USD"). If None, returns all. category: Filter by category (e.g., "Forex CFDs", "Index CFDs", "Commodity CFDs", "Metals CFDs", "Bonds CFDs"). include_status: Include current open/closed status (default True). Returns: For each instrument: - timezone: IANA timezone (e.g., "America/New_York") - windows: Array of {days, open, close} in LOCAL time - windows_utc: Same windows converted to UTC - category: Asset category - is_open: Current status (if include_status=True) - displayName: Human-readable name Examples: - get_market_hours(instrument="EUR_USD") - Single instrument - get_market_hours(category="Index CFDs") - All indices - get_market_hours(include_status=False) - All instruments, no status check

Check if a specific market is currently open for trading. Args: instrument: The OANDA instrument name (e.g., "EUR_USD", "US30_USD", "XAU_USD"). at_time: Optional ISO8601 datetime to check (e.g., "2024-01-15T14:30:00Z"). Defaults to current time if not provided. Returns: - instrument: The queried instrument - is_open: Boolean - True if market is open - checked_at_utc: When the check was made (UTC) - checked_at_local: Same time in instrument's local timezone - timezone: The instrument's native timezone - category: Asset category (Forex CFDs, Index CFDs, etc.) - displayName: Human-readable name - reason: Why the market is open/closed - schedule: Schedule type if available (e.g., "24/5", "24/7") - dstAffected: Whether DST affects trading hours Example: is_market_open(instrument="US30_USD") is_market_open(instrument="SUGAR_USD", at_time="2024-01-15T10:00:00-05:00")

Get all available market categories and instrument counts. Useful for understanding what categories can be queried with get_market_hours. Returns: List of categories with counts and sample instruments.

Get instrument specifications (precision, limits, margin, financing rates). Args: instrument: Specific instrument (e.g., "EUR_USD"). If None, returns all or filtered by type. type_filter: Filter by type: "CURRENCY", "METAL", "CFD". If None, returns all. include: List of field groups to include. Options: ["precision", "limits", "margin", "financing", "gslo", "trailing"] If None, includes all fields. Returns: For each instrument: - displayName: Human-readable name - type: CURRENCY, METAL, CFD - precision: pip location, display precision, trade units precision - limits: min trade size, max order units, max position size - margin: rate and calculated leverage (e.g., "30:1") - financing: longRate, shortRate, tripleSwapDay - gslo: guaranteed stop loss mode, min distance, premium - trailingStop: min/max distance - meta: cache age, staleness status Examples: - get_instrument_specs(instrument="EUR_USD") - Single instrument - get_instrument_specs(type_filter="METAL") - All metals - get_instrument_specs(instrument="XAU_USD", include=["precision", "margin"]) - Specific fields

Manually refresh instrument data from OANDA API. Updates financing rates, margin requirements, and other parameters. Requires: User must have saved OANDA credentials via save_oanda_credentials. Returns: - success: Boolean indicating if refresh succeeded - message: Status message - count: Number of instruments refreshed - refreshedAt: Timestamp of refresh Note: This fetches fresh data from OANDA's practice environment. The cache is automatically refreshed on server startup if data is >24 hours old.

Check the status of the instrument data cache. Returns: - ageHours: How old the cached data is - isStale: True if data is older than 24 hours - lastRefreshed: When the cache was last updated - instrumentCount: Number of instruments in cache - recommendation: Whether refresh is recommended

Return the current user's token balances from Auth0 app_metadata. Uses _safe_profile() so that the same values shown inside AI analysis (token_quota, purchased_tokens, total_token_usage, last_reset, email, user_id) are returned in a simple JSON structure.

Return supported asset symbols from config.OANDA_UNIVERSE. Optional: • filter: substring (case-insensitive) to narrow the list • asset: specific symbol to test membership

Run a one-shot technical analysis for a single asset/timeframe. Args: asset: Asset symbol (e.g., EUR_USD, XAU_USD) timeframe: Timeframe for analysis (D, H4, H1, etc.) priceType: Price type - B (bid), A (ask), or M (mid) timeoutSec: Timeout in seconds (5-120) Returns: Analysis results with status, signals, and recommendations

View the current assets in your saved watchlist. Returns: List of saved assets and count.

Add a new asset to your persistent watchlist. Args: asset: Asset symbol (e.g. 'EUR_USD', 'BTC_USD')

Remove an asset from your persistent watchlist. Args: asset: Asset symbol to remove

Analyze multiple assets from the user's SAVED watchlist in parallel. Args: timeframe: Timeframe (D, H4, H1, etc.) priceType: B (bid), A (ask), or M (mid) timeoutSec: Overall timeout in seconds (30-300) (optional) timeframes: list of timeframes (timeframes mode) – if provided, supersedes timeframe (optional) max_assets: limit how many watchlist assets to analyze (default: all) Returns: Results for all watchlist assets with analysis data

Analyze a single asset across multiple timeframes simultaneously. Args: asset: Asset symbol (e.g., EUR_USD) timeframes: List of timeframes (e.g., ["D", "H4", "H1"]) priceType: B (bid), A (ask), or M (mid) timeoutSec: Overall timeout in seconds (30-300) Returns: Multi-timeframe analysis results

Fetch upcoming economic events via the TradingView proxy source. Args: fromDays: Start of date range (days from now, 0-90) toDays: End of date range (days from now, 0-90) Returns: List of economic events with importance, country, and timing

Get recent articles from the Forex-GPT blog feed. Args: max_results: Maximum number of articles to return (1-50, default: 10) Returns: List of recent blog articles with titles, URLs, summaries, images, and publication dates

Comprehensive health and status check including optional upstream dependencies. Args: checkOpenAI: Verify OpenAI API connectivity checkTradingView: Verify TradingView API connectivity checkOANDA: Verify OANDA API connectivity Returns: Health status with environment info and dependency checks

Retrieve OHLC (candlestick) data for charting. Args: asset: Asset symbol (e.g., EUR_USD) timeframe: Timeframe (D, H4, H1, etc.) count: Number of candles (50-5000) Returns: Candlestick data with timestamps, open, high, low, close prices

Generates a real-time Sentiment Heatmap snapshot. Behavior: 1. If 'assets' are provided, scans those specific assets. 2. If 'assets' not provided, scans the user's saved Watchlist. 3. If Watchlist is empty, scans a default list of popular global assets. Args: assets: Optional list of symbols. timeframe: Granularity (e.g. 'H1', 'D').

Search forex analysis results by asset name, timeframe, or keywords. Returns a list of available analyses matching the search criteria. Args: query: Search query (e.g., "EUR_USD", "daily analysis", "gold", "bitcoin") Returns: Search results with IDs for fetching full analysis

Retrieve complete forex analysis by ID. Args: id: Analysis ID in format "ASSET_TIMEFRAME" (e.g., "EUR_USD_D", "XAU_USD_H4") Returns: Full analysis document with technical indicators, signals, and recommendations

Scans the entire market universe (Forex, Crypto, Metals, Indices) to find the strongest trading opportunities. Args: timeframes: List of timeframes to scan (e.g. ["H1", "H4", "D"]). Default is ["H8"]. min_score: Minimum absolute sentiment score (0-100) to include. Default 80 (Bullish/Bearish). limit: Maximum number of results to return. Default 6. Returns: A list of the top opportunities ranked by sentiment strength.

Checks the current liquidity and trading cost (spread) for an asset. Useful for checking if a market is too expensive to trade right now. Args: asset: The asset symbol (e.g., "EUR_USD", "XAU_USD") Returns: Current spread, average spread, and cost in basis points.

Return the server's current UTC timestamp (ISO 8601).

Master tutorial for MCP tools: usage tips, key parameters, and suggested flows.

Return a short-lived URL for the raw price stream (SSE) for given instruments. The URL expires after ~10 minutes.

Return a short-lived URL for the sentiment stream (SSE) for given instruments and granularity. The URL expires after ~10 minutes.

Proxy to the Flask /api/chart-chat endpoint using the caller's bearer token. Keeps token accounting/auth consistent with the web app while exposing chat via MCP.