Skip to main content
Glama
ForexNewsRadar MCP Server

ForexNewsRadar MCP Server

Official
README.md
<div align="center">
  <a href="https://forexnewsradar.com">
    <img src="./docs/assets/banner-hero.png" alt="ForexNewsRadar — 18-Pair FX & Gold Macro Radar & Prop-Firm VETO Shield" width="100%" />
  </a>

  <br />
  <br />

  <h1>ForexNewsRadar MCP Server &amp; Zero-DLL MT5 PropShield SDK</h1>

  <p>
    <strong>Official Remote MCP Client SDK (<code>com.forexnewsradar/mcp</code>), Hardened Zero-Dependency Stdio Bridge,<br />
    and Zero-DLL MetaTrader 5 Prop-Firm News Shield (<code>.mq5</code> / <code>.mqh</code>)</strong>
  </p>

  <p>
    <a href="https://registry.modelcontextprotocol.io/?q=com.forexnewsradar"><img src="https://img.shields.io/badge/Official_MCP_Registry-com.forexnewsradar%2Fmcp-0F172A?style=for-the-badge&logo=modelcontextprotocol&logoColor=10B981" alt="Official MCP Registry" /></a>
    <a href="https://forexnewsradar.com/.well-known/mcp.json"><img src="https://img.shields.io/badge/MCP_Spec-2026--07--28_HTTP-111827?style=for-the-badge&logoColor=38BDF8" alt="MCP 2026-07-28" /></a>
    <a href="./LICENSE"><img src="https://img.shields.io/badge/License-MIT-111827?style=for-the-badge&logoColor=F59E0B" alt="MIT License" /></a>
    <a href="./SECURITY.md"><img src="https://img.shields.io/badge/Security-100%25_Read--Only-111827?style=for-the-badge&logoColor=10B981" alt="Read-Only Security" /></a>
    <a href="./mt5/ForexNewsRadar_PropShield.mq5"><img src="https://img.shields.io/badge/MetaTrader_5-Zero--DLL_MQL5-111827?style=for-the-badge&logoColor=F59E0B" alt="Zero-DLL MQL5" /></a>
  </p>

  <p>
    <a href="https://forexnewsradar.com">Live Terminal</a> &nbsp;&bull;&nbsp;
    <a href="https://forexnewsradar.com/?mcp=1">MCP Setup</a> &nbsp;&bull;&nbsp;
    <a href="https://forexnewsradar.com/solutions">Engineering Playbooks</a> &nbsp;&bull;&nbsp;
    <a href="https://forexnewsradar.com/guides">Video Academy</a> &nbsp;&bull;&nbsp;
    <a href="https://forexnewsradar.com/openapi.json">OpenAPI 3.1</a> &nbsp;&bull;&nbsp;
    <a href="https://forexnewsradar.com/llms.txt">llms.txt</a>
  </p>
</div>

---

## Overview

**[ForexNewsRadar](https://forexnewsradar.com)** provides real-time 18-pair FX & Metals (`XAUUSD`, `XAGUSD`) macro surprise telemetry (`surprise_z`), strict prop-firm `T-5m` pre-news and 5-minute post-release blackouts (**FTMO**, **FundingPips**, **The5ers**), and post-release `VETO` shields (two-way whipsaw, foreign-print collisions, and central bank press-conference toxicity).

This open-source repository ships the official client tooling, MQL5 integration files, local zero-dependency Stdio-to-HTTP bridge, and registry manifests. The production Streamable HTTP MCP server runs on Cloudflare Edge at **`https://forexnewsradar.com/mcp`**.

<p align="center">
  <a href="https://forexnewsradar.com">
    <picture>
      <source media="(prefers-color-scheme: dark)" srcset="./docs/assets/terminal-dark.png" />
      <source media="(prefers-color-scheme: light)" srcset="./docs/assets/terminal-light.png" />
      <img src="./docs/assets/terminal-dark.png" alt="ForexNewsRadar Live Signal Inspector & 4-Guard Prop-Firm Shield" width="100%" />
    </picture>
  </a>
</p>

---

## System Architecture

One real-time risk engine serves human desks, MetaTrader 5 bots (including closed-source `.ex5` EAs), and AI coding/trading agents without duplicating calendar scraping or broker clock offsets:

```mermaid
flowchart LR
  Edge["ForexNewsRadar Cloudflare Edge\n18 FX & Metals · Quant Surprise (σ) + 4-Guard VETO"]

  Edge -->|"Streamable HTTP MCP\nPOST /mcp (2026-07-28)"| Agents["AI Agents & Native Clients\nClaude Code · Cursor · Codex · Grok · MT5 MCP"]
  Edge -->|"Zero-Dep Stdio Bridge\nbridge/fnr-mcp-bridge.mjs"| Stdio["Stdio-Only Hosts\nClaude Desktop · Windsurf · Cline · Antigravity"]
  Edge -->|"Compact JSON (4 req/min)\nGET /api/v1/pairs?compact=1"| Hub["MT5 Master Hub EA\nmt5/ForexNewsRadar_PropShield.mq5"]

  Hub -->|"GlobalVariableTemp()\n~0.001ms Volatile RAM Bus"| EAs["Custom .mq5 EAs\nmt5/ForexNewsRadar.mqh"]
  Hub -->|"OnTradeTransaction()\n8/min Hyperactivity Cap"| Ex5["Compiled .ex5 Bots\nPending-Order Sweep Only"]
```

---

## Repository Contents

```text
.
├── package.json                        # Zero-dependency Node.js >=18.17 package & npx CLI bin
├── server.json                         # Official MCP Registry manifest (com.forexnewsradar/mcp)
├── glama.json                          # Glama MCP directory ownership manifest
├── SECURITY.md                         # Security policy, read-only guarantees & disclosure contact
├── bridge/
│   └── fnr-mcp-bridge.mjs              # Zero-dependency Node.js Stdio -> Streamable HTTP bridge
├── mt5/
│   ├── ForexNewsRadar_PropShield.mq5   # Zero-DLL single-chart MT5 Master Hub EA + HUD + RAM bus
│   └── ForexNewsRadar.mqh              # Drop-in MQL5 header (RAM bus reader + 18-slot WebRequest fallback)
├── docs/
│   └── assets/                         # Terminal, MCP & MT5 visual references
├── .gitignore
└── LICENSE                             # MIT License
```

---

## 1. Remote Streamable HTTP MCP Server (`com.forexnewsradar/mcp`)

<p align="center">
  <a href="https://forexnewsradar.com/?mcp=1">
    <img src="./docs/assets/mcp-drawer.png" alt="ForexNewsRadar Built-In MCP Server Drawer & Live 18-Pair Board" width="100%" />
  </a>
</p>

| Property | Value |
| :--- | :--- |
| **Official Registry ID** | [`com.forexnewsradar/mcp`](https://registry.modelcontextprotocol.io/?q=com.forexnewsradar) |
| **Production Endpoint** | `https://forexnewsradar.com/mcp` |
| **Protocol Compatibility** | `2026-07-28` (`SEP-2575` `server/discover` + `SEP-2549` caching), `2025-11-25`, `2025-06-18`, `2025-03-26`, `2024-11-05` |
| **Discovery Metadata** | [`/.well-known/mcp.json`](https://forexnewsradar.com/.well-known/mcp.json) (RFC 8615) &nbsp;&bull;&nbsp; [`/.well-known/oauth-protected-resource`](https://forexnewsradar.com/.well-known/oauth-protected-resource) (RFC 9728) |
| **Authentication** | `Authorization: Bearer <FNR_API_KEY>` (fixed-term pass from [`forexnewsradar.com`](https://forexnewsradar.com/?mcp=1), zero auto-renewal; `EURUSD` REST & discovery endpoints require no key) |

### Claude Code (1-Line CLI)

```bash
export FNR_API_KEY="fnr_live_your_token_here"
claude mcp add --transport http forexnewsradar https://forexnewsradar.com/mcp \
  --header "Authorization: Bearer $FNR_API_KEY"
```

### Cursor / Standard `.mcp.json`

```json
{
  "mcpServers": {
    "forexnewsradar": {
      "type": "http",
      "url": "https://forexnewsradar.com/mcp",
      "headers": {
        "Authorization": "Bearer ${FNR_API_KEY}"
      }
    }
  }
}
```

### Native MetaTrader 5 MCP Client

In current MetaTrader 5 builds with native MCP client support:
1. Open `Tools -> Options -> MCP`.
2. Click **`+ Add new MCP server`**.
3. Set **Endpoint** to `https://forexnewsradar.com/mcp` and paste your `FNR_API_KEY` into **API key**.

### Stdio-Only Hosts (Claude Desktop, Windsurf, Cline, Antigravity)

Run the zero-dependency Node.js (`>=18.17.0`) bridge directly via `npx`, or clone this repository and point to `bridge/fnr-mcp-bridge.mjs`:

```json
{
  "mcpServers": {
    "forexnewsradar": {
      "command": "npx",
      "args": ["-y", "github:ForexNewsRadar/forexnewsradar-mcp"],
      "env": {
        "FNR_API_KEY": "fnr_live_your_token_here"
      }
    }
  }
}
```

When cloning locally, you can avoid putting tokens inside IDE config files altogether by saving `FNR_API_KEY=fnr_live_...` inside a gitignored `.env` file in the repository root (`bridge/fnr-mcp-bridge.mjs` reads it automatically).

### Five Strictly Read-Only MCP Tools

All five tools enforce an `Object.hasOwn` parameter allowlist (failing closed on unknown arguments) and normalize spoken aliases (`GOLD -> XAUUSD`, `SILVER -> XAGUSD`) plus broker suffixes (`EURUSD.pro`, `XAUUSDm`, `mEURUSD`) server-side:

| Tool | Purpose & Returned Fields |
| :--- | :--- |
| `check_prop_trade_gate` | Instant pre-trade gate returning `prop_safe_to_trade`, `T-5m` pre/post blackout state, `VETO` reason, directional bias (`BUY` / `SELL` / `NEUTRAL`), `wait_seconds`, and `surprise_z` |
| `get_pair_telemetry` | Full instrument telemetry: `live_state`, `agent_guidance`, next Tier-1 catalyst countdown, recent macro prints (`Actual vs. Forecast`, `surprise_z`), and closed ECN fills |
| `list_radar_pairs` | Multi-pair snapshot across Tokyo, London, and New York sessions (`all`, `unlocked`, `active_signals`, `Metals`, `USD`, `EUR`, `JPY`, `GBP`) |
| `get_macro_feed` | Unified stream of upcoming Red-Folder catalysts, active `PRE_NEWS` / `VETO` locks, and recent macro prints |
| `get_entitlement_status` | Introspects unlocked pair scopes, key expiry timestamp, and per-minute quota (`240 req/min`) |

---

## 2. Zero-DLL MetaTrader 5 PropShield EA & MQL5 SDK

<p align="center">
  <a href="https://forexnewsradar.com/solutions/prop-firm-news-rule-mt5-ea">
    <img src="./docs/assets/mt5-propshield.png" alt="ForexNewsRadar Zero-DLL MQL5 PropShield & 250-Byte Compact API" width="100%" />
  </a>
</p>

[`mt5/ForexNewsRadar_PropShield.mq5`](./mt5/ForexNewsRadar_PropShield.mq5) eliminates the silent empty `CalendarValueHistory()` / `MqlCalendarValue` fail-open bug on white-label prop-firm servers with zero DLLs:

1. Attach `ForexNewsRadar_PropShield.mq5` to **one chart** (for example `EURUSD`).
2. Whitelist `https://forexnewsradar.com` in `Tools -> Options -> Expert Advisors -> Allow WebRequest for listed URL`.
3. Every 15 seconds (`4 req/min`), the Hub EA fetches `GET /api/v1/pairs?compact=1`, draws lightweight `OBJ_LABEL` status badges across all open charts, and updates volatile RAM globals via `GlobalVariableTemp()`:

| Volatile RAM Global | Semantics |
| :--- | :--- |
| `FNR_HEARTBEAT_TS` | UTC epoch timestamp of the last valid sync (fail-closed if missing or older than `45s`) |
| `FNR_PROP_SAFE_<SYM>` | `1.0` when clear to trade; `0.0` during `T-5m PRE_NEWS`, 5-minute post-release window, `VETO`, stale feed, or locked pair |
| `FNR_WAIT_SEC_<SYM>` | Exact countdown in seconds until the restricted news window clears |
| `FNR_BIAS_<SYM>` | `1.0` (`BUY`), `-1.0` (`SELL`), or `0.0` (`NEUTRAL`) |
| `FNR_UNLOCKED_<SYM>` | `1.0` if the pair is unlocked on the active key |

For compiled third-party `.ex5` bots without source code, optional pending-order protection (`InpDeletePendingOnVeto = true`, `false` by default) intercepts resting and newly submitted pending orders via `OnTradeTransaction(TRADE_TRANSACTION_ORDER_ADD)` during active `PRE_NEWS` / `VETO` windows, **never touches open market positions**, and enforces an `InpMaxDeletesPerMin = 8` circuit breaker against prop-firm Server Hyperactivity bans.

### Drop-In MQL5 Check (`mt5/ForexNewsRadar.mqh`)

Copy [`mt5/ForexNewsRadar.mqh`](./mt5/ForexNewsRadar.mqh) into `MQL5/Include/`:

```mql5
#include <ForexNewsRadar.mqh> // Place ForexNewsRadar.mqh inside MQL5/Include/

input string InpFnrApiKey = ""; // Optional when PropShield Hub EA runs on EURUSD, or for free EURUSD

void OnTick() {
   // Returns true inside Strategy Tester (MQL_TESTER),
   // reads PropShield RAM globals in ~0.001ms when fresh (<= 45s),
   // or falls back to a cached 18-slot WebRequest().
   if(!FNR_IsPropSafe(_Symbol, InpFnrApiKey)) {
      return;
   }
   // Continue normal entry logic
}
```

---

## 3. Test the Live Wire Without an API Key

`EURUSD` telemetry and MCP discovery metadata are open with no API key required:

```bash
# RFC 8615 MCP Server Card (2026-07-28 capabilities & tool schemas)
curl -sS https://forexnewsradar.com/.well-known/mcp.json

# Full EUR/USD live telemetry (radar_health, agent_guidance, recent sigma releases)
curl -sS https://forexnewsradar.com/api/v1/pairs/EURUSD

# ~250-byte flat JSON payload tailored for MQL5 WebRequest() char[] buffers
curl -sS "https://forexnewsradar.com/api/v1/pairs/EURUSD?compact=1"
```

---

## 4. Security & Read-Only Guarantees

See [`SECURITY.md`](./SECURITY.md) for the full disclosure policy:
- **100% Read-Only MCP:** None of the 5 MCP tools can place, modify, or close trades, or access broker accounts.
- **Fail-Closed Validation:** Unknown tool arguments (`Object.hasOwn` allowlist), stale heartbeats, and HTTP 402/5xx errors default to `prop_safe_to_trade: false`.
- **Hardened Stdio Bridge:** `bridge/fnr-mcp-bridge.mjs` uses zero npm dependencies, pins HTTPS requests strictly to `forexnewsradar.com`, enforces `redirect: 'error'` (preventing cross-origin Bearer leaks), and redacts `fnr_live_` tokens in error output.
- **Zero-DLL MQL5:** Both `.mq5` and `.mqh` files compile cleanly in MetaEditor using only native `WebRequest()` and `GlobalVariableTemp()`.

---

## 5. Official Platform Resources & Engineering Guides

### Core Product & Machine-Readable Specs
- **Live 18-Pair Terminal (`EUR/USD` Free Forever):** https://forexnewsradar.com
- **MCP Integration Portal & Quickstart:** https://forexnewsradar.com/?mcp=1
- **Official MCP Registry Listing:** https://registry.modelcontextprotocol.io/?q=com.forexnewsradar
- **OpenAPI 3.1 Specification:** https://forexnewsradar.com/openapi.json
- **Agent Docs (`/llms.txt` & `/llms-full.txt`):** https://forexnewsradar.com/llms.txt &nbsp;&bull;&nbsp; https://forexnewsradar.com/llms-full.txt
- **Partner & Affiliate Portal (`35%–50%`):** https://forexnewsradar.com/partners

### Engineering Playbooks (`/solutions`) & Video Academy (`/guides`)
- **[Prop-Firm News Rule MT5 EA Guide](https://forexnewsradar.com/solutions/prop-firm-news-rule-mt5-ea):** FTMO, FundingPips & The5ers `T-5m` compliance
- **[Fix Disabled `MqlCalendarValue` on Prop Servers](https://forexnewsradar.com/solutions/mqlcalendarvalue-disabled-prop-firm-fix):** Handling silent empty arrays & DST drift
- **[Delete Pending Orders Before News on `.ex5` Bots](https://forexnewsradar.com/solutions/delete-pending-orders-before-news-mt5):** Event-driven sweeps with Hyperactivity Guard
- **[Forex & Gold Macro News MCP Server Guide](https://forexnewsradar.com/solutions/forex-gold-macro-news-mcp-server):** Connecting Claude Code, Cursor, Codex, Grok & native MT5
- **[Quant Video Academy (`/guides`)](https://forexnewsradar.com/guides)** &nbsp;&bull;&nbsp; **[YouTube `@ForexNewsRadar`](https://www.youtube.com/@ForexNewsRadar)**

### Flagship Live Pair Pages & Community
- **Live Instrument Telemetry:** [EUR/USD](https://forexnewsradar.com/pairs/eurusd) &nbsp;&bull;&nbsp; [XAU/USD (Gold)](https://forexnewsradar.com/pairs/xauusd) &nbsp;&bull;&nbsp; [XAG/USD (Silver)](https://forexnewsradar.com/pairs/xagusd) &nbsp;&bull;&nbsp; [GBP/USD](https://forexnewsradar.com/pairs/gbpusd) &nbsp;&bull;&nbsp; [USD/JPY](https://forexnewsradar.com/pairs/usdjpy) &nbsp;&bull;&nbsp; [GBP/JPY](https://forexnewsradar.com/pairs/gbpjpy)
- **Engineering Deep Dive (Dev.to):** [Why MT5 `CalendarValueHistory()` Fails Prop-Firm News Rules](https://dev.to/forexnewsradar/why-mt5-calendarvaluehistory-fails-prop-firm-news-rules-and-how-to-build-a-fail-closed-gate-4o69)
- **Community & Updates:** [X `@ForexNewsRadarX`](https://x.com/ForexNewsRadarX) &nbsp;&bull;&nbsp; [Reddit `r/ForexNewsRadar`](https://www.reddit.com/r/ForexNewsRadar) &nbsp;&bull;&nbsp; [MQL5 Profile](https://www.mql5.com/en/users/forexnewsradar)