{
  "markdown": "# @xcreener/mcp\n\n[![npm version](https://img.shields.io/npm/v/@xcreener/mcp.svg)](https://www.npmjs.com/package/@xcreener/mcp)\n[![license](https://img.shields.io/npm/l/@xcreener/mcp.svg)](LICENSE)\n\nLocal stdio MCP bridge for XCREENER's XQL screener API — validate, explain, and run XQL queries from Claude Desktop, Cursor, Windsurf, or any stdio MCP client.\n\n## About XCREENER\n\n[XCREENER](https://xcreener.com) is a market screener that scans Crypto, Forex, Indices, Commodities, and Metals simultaneously, so you don't have to check charts one at a time. It's built for beginner traders through ready-made screeners as well as for developers and AI agents, who can express custom conditions in XCREENER Query Language (XQL) and run them instantly via a REST API or MCP. Learn more at [xcreener.com](https://xcreener.com).\n\n## What this MCP server does\n\nThis package is the local stdio bridge to XCREENER's XQL API specifically. It exposes `xql_validate`, `xql_explain`, `xql_run`, and `xql_nl_reference` as MCP tools, so any stdio MCP client can check and execute XQL screens against live market data without you writing any HTTP glue code.\n\n## Installation\n\n### Claude Desktop (`.mcpb`)\n\nDownload the latest `xcreener.mcpb` from this repo's [Releases](https://github.com/xcreener/xcreener-mcp/releases) page, then double-click it to install — Desktop asks for your API key in a masked field as part of that same dialog. No JSON to hand-edit, no separate Node install.\n\n### Other MCP clients (npx)\n\nAdd this to your client's MCP server config (e.g. Cursor, Windsurf, Claude Code):\n\n```json\n{\n  \"mcpServers\": {\n    \"xcreener\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@xcreener/mcp\"],\n      \"env\": { \"XCREENER_API_KEY\": \"your-api-key\" }\n    }\n  }\n}\n```\n\n### From source\n\n```bash\ngit clone https://github.com/xcreener/xcreener-mcp.git\ncd xcreener-mcp\nnpm install\nnpm run build\n```\n\nThen point your client at `node dist/index.js` with `XCREENER_API_KEY` set in its environment.\n\n## Configuration\n\n| Variable           | Required | Description                                                                                       |\n| ------------------ | -------- | ------------------------------------------------------------------------------------------------- |\n| `XCREENER_API_KEY` | Yes      | Your XCREENER API key, from [xcreener.com/account/api-key](https://xcreener.com/account/api-key). |\n\nThe key is checked lazily — an invalid or missing key won't stop the server from starting, it'll just surface as an `auth` error the first time a tool is called.\n\n## Available tools\n\n| Name              | Type | Description                                                                                     |\n| ----------------- | ---- | ------------------------------------------------------------------------------------------------- |\n| `xql_validate`     | Tool | Validate XQL query text by parsing and planning it, without executing it against live data.     |\n| `xql_explain`      | Tool | Parse and plan an XQL query, returning its execution plan and a human-readable explanation.     |\n| `xql_run`          | Tool | Parse, plan, and execute an XQL query against live market data, returning matching instruments. |\n| `xql_nl_reference` | Tool | Reference document mapping natural-language trading phrases to XQL syntax.                      |\n\n## Example session\n\nUnder the hood, the assistant calls the `xql_nl_reference` tool, translates your plain-English ask into an XQL query, and calls `xql_validate`/`xql_run` — what you see is just the human-visible conversation. A few real examples:\n\n**Multi-market screen**\n\n> **You:** check all markets and see which instruments are oversold at the moment\n>\n> **XCREENER runs** (same query per market — `CRYPTO`, `FOREX`, `INDICES`, `METALS`, `COMMODITIES`):\n> ```xql\n> market = \"CRYPTO\"\n> timeframe = h1\n> columns = [rsi(14)]\n> sort = rsi(14) asc\n> rsi(14) < 30\n> ```\n> **XCREENER:** Oversold (RSI(14) < 30, hourly) across all markets:\n>\n> | Market      | Symbol   | RSI(14) |\n> | ----------- | -------- | ------- |\n> | Crypto      | BTCUSDT  | 26.3    |\n> | Crypto      | ETHUSDT  | 27.5    |\n> | Crypto      | XRPUSDT  | 28.0    |\n> | Commodities | WHEATUSD | 21.0    |\n> | Commodities | CORNUSD  | 22.6    |\n>\n> Forex, Indices, and Metals had no oversold matches.\n\n**Single-market snapshot**\n\n> **You:** can you give me updates on how the metals are doing?\n>\n> **XCREENER runs:**\n> ```xql\n> market = \"METALS\"\n> timeframe = h1\n> let uptrend = close > sma(50)\n> columns = [close, roc(1), rsi(14), uptrend]\n> sort = roc(1) desc\n> close > 0\n> ```\n> **XCREENER:** Metals snapshot, hourly:\n>\n> | Symbol            | Close    | 1h ROC | RSI(14) | Trend (vs SMA50) |\n> | ----------------- | -------- | ------ | ------- | ---------------- |\n> | XPTUSD (Platinum) | 1,637.98 | +0.03% | 54.8    | Uptrend          |\n> | XAGUSD (Silver)   | 57.48    | +0.02% | 38.6    | Downtrend        |\n> | XAUUSD (Gold)     | 4,043.69 | +0.01% | 41.0    | Downtrend        |\n>\n> Overall: fairly quiet, no oversold/overbought extremes (all RSI 38–55). Platinum's the strongest — up-trending with the best momentum — while gold and silver are drifting below their 50-hour average.\n\n**Cross-pair aggregate analysis**\n\n> **You:** which currency is the weakest and strongest?\n>\n> **XCREENER runs:**\n> ```xql\n> market = \"FOREX\"\n> timeframe = h1\n> columns = [close, roc(1)]\n> sort = roc(1) desc\n> close > 0\n> ```\n> **XCREENER:** Based on the 1h ROC across all 28 pairs (aggregating each currency's average move against the other seven):\n>\n> | Rank          | Currency | Avg 1h Strength |\n> | ------------- | -------- | --------------- |\n> | 1 (strongest) | CHF      | +0.0414%        |\n> | 2             | JPY      | +0.0184%        |\n> | ...           |          |                 |\n> | 8 (weakest)   | USD      | -0.0421%        |\n>\n> **Strongest: CHF** — up against every other major this hour. **Weakest: USD** — sold broadly against EUR, GBP, AUD, JPY, and CHF alike.\n\n**Actionable trade plan**\n\n> **You:** NZD looks like the strongest currency this week — which pair should I long based on that, and what stop-loss/take-profit levels make sense?\n>\n> **XCREENER runs:**\n> ```xql\n> market = \"FOREX\"\n> timeframe = h1\n> symbols = [\"NZDUSD\"]\n> columns = [close, atr(14), sma(50), highest(high, 20), lowest(low, 20), w::lowest(low, 52), rsi(14)]\n> close > 0\n> ```\n> **XCREENER:** **Idea: Long NZDUSD** — the cleanest multi-timeframe confluence: NZD is the #2 strongest currency of the week, daily is non-conflicting, and hourly shows an uptrend (close 0.5881 > SMA(50) 0.5846) with bullish-but-not-overbought momentum (RSI(14) 60.8).\n>\n> |           | Level   | Rationale                                           |\n> | --------- | ------- | --------------------------------------------------- |\n> | Entry     | ~0.5881 | Current price                                       |\n> | Stop Loss | 0.5845  | Below the 20h swing low and h1 SMA(50); ~3× ATR(14) |\n> | TP1       | 0.5940  | ~1.6:1 R:R, partial scale-out                       |\n> | TP2       | 0.6093  | Weekly 52-week high, ~5.9:1 R:R                     |\n>\n> _Not financial advice — a technical read off the pulled data; confirm against execution/spread costs before entering._\n\n## Development\n\n```bash\nnpm run dev         # tsup --watch\nnpm run build        # build dist/index.js\nnpm run build:mcpb   # build + pack dist-mcpb/xcreener.mcpb\nnpm run lint\nnpm run typecheck\n```\n\nThe build produces a single bundled ESM file (`dist/index.js`) with all dependencies inlined via tsup, so both the npm package and the `.mcpb` bundle ship without `node_modules`.\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n",
  "bytes": 7691,
  "sha": "53b0e2dd6fd2bc0bd2618c7c9117ccbf93755c05598cbe865c6ebadc43d12100",
  "repo_slug": "xcreener/xcreener-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_com_xcreener_xcreener_mcp_1a0eadae/readme"
}