{
  "markdown": "# fxabsolute-mcp\n\nConnects a coding agent directly to FXAbsolute's candle history over [MCP](https://modelcontextprotocol.io).\n\nThe point is to stop the model looking at *pictures* of charts. A screenshot forces it to\nrecover prices from pixels; these tools hand it the numbers, so \"what does the New York open\nactually do\" becomes a query instead of a guess.\n\n## Setup\n\nNothing to install and no API key. The server fetches what it needs and caches it.\n\n**Claude Code**\n\n```bash\nclaude mcp add fxabsolute -- npx -y fxabsolute-mcp\n```\n\n**Cursor, Windsurf, Claude Desktop, or anything reading a config file**\n\n```json\n{\n  \"mcpServers\": {\n    \"fxabsolute\": { \"command\": \"npx\", \"args\": [\"-y\", \"fxabsolute-mcp\"] }\n  }\n}\n```\n\nVerify with `claude mcp list`, or just ask your agent *\"what instruments does fxabsolute\nhave?\"* — it should answer with fifteen, and tell you volume is not available.\n\n**Working on the server itself**\n\n```bash\ngit clone https://github.com/varsansri/fxabsolute-mcp && cd fxabsolute-mcp\nnpm install\nnpm run smoke                # every tool against real data, ~30 checks\nnode test/proto.mjs          # stdio protocol round-trip\nclaude mcp add fxabsolute -- node \"$PWD/src/index.js\"\n```\n\n## Where the data comes from\n\nIn order:\n\n1. `FXA_DATA_DIR` — an explicit directory of `.bin` files\n2. `../public/data` — automatic when running inside the checkout\n3. `FXA_ORIGIN` (default `https://www.fxabsolute.com`) — fetched once per instrument and\n   cached under `~/.cache/fxabsolute-mcp`, so it works from any machine\n\n~38 MB per instrument, downloaded lazily and only once.\n\n## Tools\n\n| Tool | What it answers |\n|---|---|\n| `fxa_instruments` | What's available, how many bars, what fields exist |\n| `fxa_candles` | Raw OHLC over a date range at any timeframe M1–W1 |\n| `fxa_session_scan` | Specific bars of a trading session across months, summarised |\n| `fxa_bucket_stats` | Movement grouped by hour / weekday / month / year |\n| `fxa_level_touches` | Whether a price level actually held, and the reaction it produced |\n\n### Live chart bridge\n\n| Tool | Purpose |\n|---|---|\n| `fxa_connect_chart` | Pair with an open chart using the code in its AI tab |\n| `fxa_wait_for_message` | Block until the trader types or speaks; returns their words + chart state |\n| `fxa_reply` | Answer into their chart panel |\n| `fxa_set_thinking` | Show the thinking indicator during a long lookup |\n| `fxa_disconnect_chart` | Leave the session |\n\nA trader opens the backtester, switches to the **AI** tab, and reads out the six-character\ncode. Their agent calls `fxa_connect_chart`, then loops on `fxa_wait_for_message` → answer →\n`fxa_reply`. The site holds no API key and pays for no inference — every trader brings their\nown agent.\n\nEach message carries a snapshot of the chart: instrument, timeframe, replay position, the\ncurrent candle, every drawing as real geometry (height in pips, bars spanned, slope per bar,\nfib levels, whether price sits inside a box), open trades and running performance. The agent\nreads numbers, so it can check a claim with `fxa_session_scan` instead of guessing from an\nimage.\n\nTransport is a Supabase Realtime broadcast channel, so the browser and the agent need not be\non the same machine — a chart on a phone pairs with a terminal on a laptop. Credentials come\nfrom `/bridge-config.json` on the site, which carries only the publishable key already present\nin every visitor's browser bundle, so pairing needs no setup.\n\nThe replay position is included with a note telling the agent not to reveal bars the trader\nhas not reached. Backtesting is worthless if the assistant spoils the future.\n\nThe motivating query — *the first 5-minute candle of the New York session, every day, for six\nmonths* — is one call:\n\n```json\n{ \"instrument\": \"SPX500\", \"session\": \"nyse\", \"timeframe\": \"M5\",\n  \"bars\": [1], \"from\": \"2024-01-01\", \"to\": \"2024-07-01\" }\n```\n\n## Two things worth knowing\n\n**There is no volume.** The binary format is 20 bytes per candle: `uint32` timestamp plus four\n`float32` OHLC values. Volume was never stored, so no tool reports it and none invents a proxy\nsilently — `rangePips` is offered instead, and every relevant response says so. Adding real\nvolume means re-fetching all ~543 MB from Dukascopy into a wider record format.\n\n**Timeframes are bucketed on wall-clock time, not by array index.** The browser chart\naggregates every N bars, which is right for bar-by-bar replay but drifts for analysis: forex\ndata has weekend and holiday gaps, so the Nth group of 60 M1 bars stops lining up with a real\nclock hour and an \"H1 candle\" can straddle a weekend. Here, bars are bucketed on\n`floor(ts / period)`, so every bar sits on a true boundary and gaps produce no bar rather than\na synthetic one.\n\nSession windows are evaluated in exchange-local time with daylight saving resolved to the\nsecond, so \"the 09:30 bar\" is the 09:30 bar in both January and July rather than drifting an\nhour each spring.\n\n`fxa_session_scan` also reports coverage: how many weekdays in the window produced no data at\nall. This matters more than it sounds — SPX500 is missing about 19% of weekdays in the first\nhalf of 2024, and without the warning a scan over that period returns clean-looking statistics\nbuilt on a fifth less data than you asked for.\n",
  "bytes": 5262,
  "sha": "55378da4d0ebce4b897b35b1f080ba1a3aaeccae5da6e2e7e80eaa6f15f98510",
  "repo_slug": "varsansri/fxabsolute-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_varsansri_fxabsolute_985db8f9/readme"
}