@xcreener/mcp
OfficialThis MCP server provides a local stdio bridge to XCREENER's XQL screener API, enabling AI assistants to validate, explain, and execute XQL queries against live market data across Crypto, Forex, Indices, Commodities, and Metals, without writing HTTP glue code. Key capabilities:
Validate XQL queries (
xql_validate): Check syntax without hitting live data.Explain XQL queries (
xql_explain): Get execution plan and human‑readable explanation.Run XQL queries (
xql_run): Execute against real‑time data, returning matching instruments.Natural language reference (
xql_nl_reference): Map plain‑English trading phrases to XQL syntax.Multi‑market screening: Target any supported market – Crypto, Forex, Indices, Commodities, Metals.
Technical analysis: Use indicators like RSI, SMA, ATR, custom
letvariables, and more.Safe workflow: Validate before running to avoid wasted live‑data round trips.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@@xcreener/mcp Which metals are oversold on the 1h chart?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
@xcreener/mcp
Local 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.
About XCREENER
XCREENER 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.
Related MCP server: tradingview-mcp-server
What this MCP server does
This 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.
Installation
Claude Desktop (.mcpb)
Download the latest xcreener.mcpb from this repo's 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.
Other MCP clients (npx)
Add this to your client's MCP server config (e.g. Cursor, Windsurf, Claude Code):
{
"mcpServers": {
"xcreener": {
"command": "npx",
"args": ["-y", "@xcreener/mcp"],
"env": { "XCREENER_API_KEY": "your-api-key" }
}
}
}From source
git clone https://github.com/xcreener/xcreener-mcp.git
cd xcreener-mcp
npm install
npm run buildThen point your client at node dist/index.js with XCREENER_API_KEY set in its environment.
Configuration
Variable | Required | Description |
| Yes | Your XCREENER API key, from xcreener.com/account/api-key. |
The 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.
Available tools
Name | Type | Description |
| Tool | Validate XQL query text by parsing and planning it, without executing it against live data. |
| Tool | Parse and plan an XQL query, returning its execution plan and a human-readable explanation. |
| Tool | Parse, plan, and execute an XQL query against live market data, returning matching instruments. |
| Tool | Reference document mapping natural-language trading phrases to XQL syntax. |
Example session
Under 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:
Multi-market screen
You: check all markets and see which instruments are oversold at the moment
XCREENER runs (same query per market —
CRYPTO,FOREX,INDICES,METALS,COMMODITIES):market = "CRYPTO" timeframe = h1 columns = [rsi(14)] sort = rsi(14) asc rsi(14) < 30XCREENER: Oversold (RSI(14) < 30, hourly) across all markets:
Market
Symbol
RSI(14)
Crypto
BTCUSDT
26.3
Crypto
ETHUSDT
27.5
Crypto
XRPUSDT
28.0
Commodities
WHEATUSD
21.0
Commodities
CORNUSD
22.6
Forex, Indices, and Metals had no oversold matches.
Single-market snapshot
You: can you give me updates on how the metals are doing?
XCREENER runs:
market = "METALS" timeframe = h1 let uptrend = close > sma(50) columns = [close, roc(1), rsi(14), uptrend] sort = roc(1) desc close > 0XCREENER: Metals snapshot, hourly:
Symbol
Close
1h ROC
RSI(14)
Trend (vs SMA50)
XPTUSD (Platinum)
1,637.98
+0.03%
54.8
Uptrend
XAGUSD (Silver)
57.48
+0.02%
38.6
Downtrend
XAUUSD (Gold)
4,043.69
+0.01%
41.0
Downtrend
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.
Cross-pair aggregate analysis
You: which currency is the weakest and strongest?
XCREENER runs:
market = "FOREX" timeframe = h1 columns = [close, roc(1)] sort = roc(1) desc close > 0XCREENER: Based on the 1h ROC across all 28 pairs (aggregating each currency's average move against the other seven):
Rank
Currency
Avg 1h Strength
1 (strongest)
CHF
+0.0414%
2
JPY
+0.0184%
...
8 (weakest)
USD
-0.0421%
Strongest: CHF — up against every other major this hour. Weakest: USD — sold broadly against EUR, GBP, AUD, JPY, and CHF alike.
Actionable trade plan
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?
XCREENER runs:
market = "FOREX" timeframe = h1 symbols = ["NZDUSD"] columns = [close, atr(14), sma(50), highest(high, 20), lowest(low, 20), w::lowest(low, 52), rsi(14)] close > 0XCREENER: 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).
Level
Rationale
Entry
~0.5881
Current price
Stop Loss
0.5845
Below the 20h swing low and h1 SMA(50); ~3× ATR(14)
TP1
0.5940
~1.6:1 R:R, partial scale-out
TP2
0.6093
Weekly 52-week high, ~5.9:1 R:R
Not financial advice — a technical read off the pulled data; confirm against execution/spread costs before entering.
Development
npm run dev # tsup --watch
npm run build # build dist/index.js
npm run build:mcpb # build + pack dist-mcpb/xcreener.mcpb
npm run lint
npm run typecheckThe 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.
License
MIT — see LICENSE.
Available Tools
4 toolsxql_explainA
Parse and plan an XQL query, returning its execution plan and a human-readable explanation.
Inputs: query (required).
xql_nl_referenceA
Fetch the XQL natural-language reference document, mapping retail-trader phrasing to valid XQL syntax and documenting hard limits (300-bar lookback ceiling, closed market/timeframe enums, the atr no-source-argument exception, etc.). Call this before writing a query, or after xql_validate/xql_explain/xql_run returns isError: true, to see the exact construct you likely got wrong.
Inputs: no named parameters.
xql_runA
Parse, plan, and execute an XQL query against live market data, returning matching instruments. Call xql_validate on the query first to catch syntax errors before spending a live-data round trip on this call.
Inputs: query (required).
xql_validateA
Validate XQL query text by parsing and planning it, without executing it against live data.
Inputs: query (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool has a clearly distinct role: validate parses/plans without execution, explain returns the execution plan and explanation, run executes against live data, and nl_reference fetches documentation. There is no overlap in purpose despite validate and explain sharing a parsing/planning step.
All tool names share the consistent 'xql_' prefix, but the pattern after the prefix is not perfectly uniform: three use a verb (validate, explain, run) while one uses a noun phrase (nl_reference). Still readable and predictable, with minor deviation.
With only 4 tools, the server is tightly focused on XQL query operations: validate, explain, run, and reference. Each tool serves a necessary function in the query workflow without redundancy.
The tool surface covers the full query lifecycle: reference for syntax, validate for error checking, explain for plan analysis, and run for execution. No obvious gaps exist given the stated purpose of an XQL query server.
Maintenance
Related MCP Connectors
Query SEC EDGAR filings, XBRL financials, and company data via MCP. STDIO or Streamable HTTP.
Financial data MCP server for Claude, ChatGPT, Cursor and Codex. Real-time stock quotes, financial statements, options flow, SEC filings, insider trades, 13F holdings, macro data and market news from gloom.sh, the open-source Bloomberg Terminal alternative.
Talk to your public-facing AI from any MCP client — Claude, ChatGPT, Cursor, Cline, Windsurf.
TradeOS MCP: ticker search, My Agent, chart TA, macro news. npm stdio or HTTP.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceMCP server for screening Indian stocks and mutual funds by wrapping screener.in and Morningstar India, enabling fundamental queries from Claude or Cursor.-
- AlicenseAqualityCmaintenanceMCP server for TradingView's market screener API, enabling stock, forex, crypto, and ETF screening, technical analysis, and investor workflows via Claude or CLI.12324 npm52MIT
- AlicenseBqualityDmaintenanceA resilient MCP server wrapping FiinQuant/FiinQuantX Python SDK for Claude Desktop and Cursor, providing market data, fundamental analysis, screening, and technical indicators via stdio with timeouts, error envelopes, and free-tier guards.26MIT
- AlicenseNot gradedqualityCmaintenanceConverts plain-English stock requests (e.g. "compare Apple and Microsoft YTD") into validated yfinance/matplotlib scripts, AST-checked and executed in a sandbox to produce chart PNGs. Exposes parsing, saving, execution, and history-listing tools to Claude Desktop and Claude Code through FastMCP, backed by local Ollama/DeepSeek-R1 or cloud Groq/GPT-4o models.MIT