io.github.varsansri/fxabsolute
Five years of 1-minute forex, index and crypto candles, plus a live bridge to a trader's chart.
Open source Open in the app JSON README (API)
About
Five years of 1-minute forex, index and crypto candles, plus a live bridge to a trader's chart.
Details
- Kind
- MCP servers
- Topic
- Finance & crypto
- Publisher
- varsansri
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.1.0
- Last push
- 2026-08-28T10:33:58Z
- Repository state
- ativo
- Language
- JavaScript
- License
- MIT
- Added
- 2026-08-29 04:01:37
- Updated
- 2026-08-29 04:01:37
- Origin id
io.github.varsansri/fxabsolute
README
# fxabsolute-mcp
Connects a coding agent directly to FXAbsolute's candle history over [MCP](https://modelcontextprotocol.io).
The point is to stop the model looking at *pictures* of charts. A screenshot forces it to
recover prices from pixels; these tools hand it the numbers, so "what does the New York open
actually do" becomes a query instead of a guess.
## Setup
Nothing to install and no API key. The server fetches what it needs and caches it.
**Claude Code**
```bash
claude mcp add fxabsolute -- npx -y fxabsolute-mcp
```
**Cursor, Windsurf, Claude Desktop, or anything reading a config file**
```json
{
"mcpServers": {
"fxabsolute": { "command": "npx", "args": ["-y", "fxabsolute-mcp"] }
}
}
```
Verify with `claude mcp list`, or just ask your agent *"what instruments does fxabsolute
have?"* — it should answer with fifteen, and tell you volume is not available.
**Working on the server itself**
```bash
git clone https://github.com/varsansri/fxabsolute-mcp && cd fxabsolute-mcp
npm install
npm run smoke # every tool against real data, ~30 checks
node test/proto.mjs # stdio protocol round-trip
claude mcp add fxabsolute -- node "$PWD/src/index.js"
```
## Where the data comes from
In order:
1. `FXA_DATA_DIR` — an explicit directory of `.bin` files
2. `../public/data` — automatic when running inside the checkout
3. `FXA_ORIGIN` (default `https://www.fxabsolute.com`) — fetched once per instrument and
cached under `~/.cache/fxabsolute-mcp`, so it works from any machine
~38 MB per instrument, downloaded lazily and only once.
## Tools
| Tool | What it answers |
|---|---|
| `fxa_instruments` | What's available, how many bars, what fields exist |
| `fxa_candles` | Raw OHLC over a date range at any timeframe M1–W1 |
| `fxa_session_scan` | Specific bars of a trading session across months, summarised |
| `fxa_bucket_stats` | Movement grouped by hour / weekday / month / year |
| `fxa_level_touches` | Whether a price level actually held, and the reaction it produced |
### Live chart bridge
| Tool | Purpose |
|---|---|
| `fxa_connect_chart` | Pair with an open chart using the code in its AI tab |
| `fxa_wait_for_message` | Block until the trader types or speaks; returns their words + chart state |
| `fxa_reply` | Answer into their chart panel |
| `fxa_set_thinking` | Show the thinking indicator during a long lookup |
| `fxa_disconnect_chart` | Leave the session |
A trader opens the backtester, switches to the **AI** tab, and reads out the six-character
code. Their agent calls `fxa_connect_chart`, then loops on `fxa_wait_for_message` → answer →
`fxa_reply`. The site holds no API key and pays for no inference — every trader brings their
own agent.
Each message carries a snapshot of the chart: instrument, timeframe, replay position, the
current candle, every drawing as real geometry (height in pips, bars spanned, slope per bar,
fib levels, whether price sits inside a box), open trades and running performance. The agent
reads numbers, so it can check a claim with `fxa_session_scan` instead of guessing from an
image.
Transport is a Supabase Realtime broadcast channel, so the browser and the agent need not be
on the same machine — a chart on a phone pairs with a terminal on a laptop. Credentials come
from `/bridge-config.json` on the site, which carries only the publishable key already present
in every visitor's browser bundle, so pairing needs no setup.
The replay position is included with a note telling the agent not to reveal bars the trader
has not reached. Backtesting is worthless if the assistant spoils the future.
The motivating query — *the first 5-minute candle of the New York session, every day, for six
months* — is one call:
```json
{ "instrument": "SPX500", "session": "nyse", "timeframe": "M5",
"bars": [1], "from": "2024-01-01", "to": "2024-07-01" }
```
## Two things worth knowing
**There is no volume.** The binary format is 20 bytes per candle: `uint32` timestamp plus four
`float32` OHLC values. Volume was never stored, so no tool reports it and none invents a proxy
silently — `rangePips` is offered instead, and every relevant response says so. Adding real
volume means re-fetching all ~543 MB from Dukascopy into a wider record format.
**Timeframes are bucketed on wall-clock time, not by array index.** The browser chart
aggregates every N bars, which is right for bar-by-bar replay but drifts for analysis: forex
data has weekend and holiday gaps, so the Nth group of 60 M1 bars stops lining up with a real
clock hour and an "H1 candle" can straddle a weekend. Here, bars are bucketed on
`floor(ts / period)`, so every bar sits on a true boundary and gaps produce no bar rather than
a synthetic one.
Session windows are evaluated in exchange-local time with daylight saving resolved to the
second, so "the 09:30 bar" is the 09:30 bar in both January and July rather than drifting an
hour each spring.
`fxa_session_scan` also reports coverage: how many weekdays in the window produced no data at
all. This matters more than it sounds — SPX500 is missing about 19% of weekdays in the first
half of 2024, and without the warning a scan over that period returns clean-looking statistics
built on a fifth less data than you asked for.