de en es ja ko ru zh

QUOTEZ

Name: QUOTEZ
Author: PNX89

by PNX89

Overview Schema Source Related Servers Discussions Admin

Python

Local

QUOTEZ

Marktdaten für Agenten. Nur lesend durch Konstruktion, nicht durch Konfiguration.

Python License: MIT

Ein MCP-Server, der MetaTrader 5-Marktdaten als typisierte, schreibgeschützte Tools bereitstellt, die ein LLM-Agent aufrufen kann. Python 3.11 oder neuer, eine Laufzeitabhängigkeit, stdio-Transport. Das Badge endet bei 3.13, weil dort die Klassifikatoren enden; CI führt auch einen 3.14-Durchlauf durch, der als hinweisend markiert ist, und 3.14 kommt zum Badge hinzu, sobald es lange genug grün war, um ein Versprechen und nicht nur eine Hoffnung zu sein.

Ein Agent ist nur so gut wie die Tools, die man ihm gibt, und bei Marktdaten richtet ein schlampiges Tool echten Schaden an. Das Modell gibt alles, was ein Tool zurückgibt, als Tatsache wieder, sodass eine Nutzlast ohne Einheiten, Zeitzone und Herkunft zu einem selbstbewussten Satz über einen Preis wird, auf den jemand reagieren könnte. QUOTEZ antwortet mit generierten Ausgabeschemata anstelle von Textblobs, UTC überall, einem synthetic-Flag auf jeder Nutzlast und keinem Schreibpfad im Code.

Dies ist ein Tool, das so gebaut ist, dass es keinen Schaden anrichten kann – eine kleinere und besser überprüfbare Frage, als ob einem Agenten als Ganzes mit Tools vertraut werden kann. Diese größere Frage ist Sache von QUELLZ.

Umfang und Grenzen

Nur lesend: kein order_send, kein order_check, kein symbol_select, keinerlei Schreibvorgänge.
Live-MetaTrader-Daten benötigen Windows und ein laufendes Terminal; die Räder sind nur win_amd64.
Die Standardquelle spielt generierte Daten ab und kennzeichnet jede Nutzlast mit synthetic: true.
Zeiten sind UTC und jeder Balken wird durch seinen Eröffnungskurs, den linken Rand seines Intervalls, gekennzeichnet.

Related MCP server: ibkr-mcp

Beispiel-Agenten-Sitzung

Echte Ausgabe, kein Einfügen. Neu generieren mit uv run python examples/agent_session.py; tests/test_readme.py prüft diesen Block Byte für Byte gegen die Standardausgabe dieses Befehls. Die Wiedergabepreise werden generiert, nicht von einem Markt aufgezeichnet.

QUOTEZ over an in-memory MCP client, source=replay.
Every price below is generated. This repository bundles no real market data.

>>> list_symbols(group="*FX*")
{
  "source": "replay",
  "synthetic": true,
  "count": 2,
  "symbols": [
    {"name": "SYNTH_FX_ALPHA", "description": "Synthetic FX pair Alpha", "digits": 5, "point": 1e-05},
    {"name": "SYNTH_FX_BETA", "description": "Synthetic FX pair Beta", "digits": 3, "point": 0.001}
  ]
}

>>> get_quote(symbol="SYNTH_FX_ALPHA")
{
  "symbol": "SYNTH_FX_ALPHA",
  "time": "2026-06-12T13:59:00Z",
  "bid": 1.08044,
  "ask": 1.08056,
  "spread_points": 12,
  "source": "replay",
  "synthetic": true
}

>>> get_bars(symbol="SYNTH_FX_ALPHA", timeframe="H1", count=5)
{
  "symbol": "SYNTH_FX_ALPHA",
  "timeframe": "H1",
  "source": "replay",
  "synthetic": true,
  "count": 5,
  "bars": [
    {"time": "2026-06-12T08:00:00Z", "open": 1.07985, "high": 1.08231, "low": 1.07978, "close": 1.08125, "tick_volume": 4257, "spread": null},
    {"time": "2026-06-12T09:00:00Z", "open": 1.08125, "high": 1.0844, "low": 1.08113, "close": 1.08302, "tick_volume": 2501, "spread": null},
    {"time": "2026-06-12T10:00:00Z", "open": 1.08302, "high": 1.08439, "low": 1.08298, "close": 1.08368, "tick_volume": 1643, "spread": null},
    {"time": "2026-06-12T11:00:00Z", "open": 1.08368, "high": 1.08395, "low": 1.08036, "close": 1.08097, "tick_volume": 1570, "spread": null},
    {"time": "2026-06-12T12:00:00Z", "open": 1.08097, "high": 1.08284, "low": 1.08084, "close": 1.08159, "tick_volume": 2589, "spread": null}
  ]
}

>>> symbol_info(symbol="SYNTH_FX_ALPHA")
{
  "name": "SYNTH_FX_ALPHA",
  "description": "Synthetic FX pair Alpha",
  "digits": 5,
  "point": 1e-05,
  "spread": 12,
  "spread_float": true,
  "trade_stops_level": 10,
  "trade_freeze_level": 0,
  "trade_tick_value": 1.0,
  "trade_tick_size": 1e-05,
  "trade_contract_size": 100000.0,
  "volume_min": 0.01,
  "volume_max": 100.0,
  "volume_step": 0.01,
  "currency_base": "SYA",
  "currency_profit": "SYN",
  "currency_margin": "SYA",
  "source": "replay",
  "synthetic": true
}

A symbol that does not exist, to show what the model actually sees:

>>> get_quote(symbol="NOT_A_SYMBOL")
is_error: true
Error executing tool get_quote: Symbol 'NOT_A_SYMBOL' is not available on this server.

Schnellstart

Ein Befehl, nichts zu konfigurieren, keine MetaTrader-Installation irgendwo:

uvx --from git+https://github.com/PNX89/QUOTEZ quotez --source replay

QUOTEZ ist nicht auf PyPI veröffentlicht, daher ist die Git-Form die Installation; fügen Sie @main, einen Tag oder einen Commit hinzu, um einen Referenzpunkt festzulegen, gemäß uvs Abhängigkeitsdokumentation. Es scheint dann zu hängen, weil stdout der JSON-RPC-Draht ist und ein Host ihn steuert. Um es ohne Host in Aktion zu sehen, klonen Sie das Repository und führen Sie die Beispielsitzung aus, die denselben Server von einem prozessinternen Client aus steuert:

git clone https://github.com/PNX89/QUOTEZ && cd QUOTEZ
uv run python examples/agent_session.py

Unter Windows, gegen ein bereits laufendes und angemeldetes Terminal:

uvx --from "quotez[mt5] @ git+https://github.com/PNX89/QUOTEZ" quotez --source mt5

Das Konsolenskript ist der einzige Einstiegspunkt, der Flags akzeptiert, und Flags gewinnen gegenüber der Umgebung. mcp run src/quotez/server.py bedient diesen Server auch über das Modul-Level mcp-Global, leitet aber nichts weiter, daher liest dieser Pfad stattdessen die Variablen.

Flag	Umgebungsvariable	Standard	Bedeutung
`--source`	`QUOTEZ_SOURCE`	`replay`	`replay` liest die gebündelten generierten Dateien, `mt5` liest ein Live-Terminal
`--symbols`	`QUOTEZ_SYMBOLS`	leer	Kommagetrennte Whitelist, Groß-/Kleinschreibung nicht beachtend. Leer gibt alles frei, was die Quelle hat
`--max-bars`	`QUOTEZ_MAX_BARS`	`1000`	Maximal Balken, die ein Aufruf zurückgeben darf, 1 bis 5000
`--log-level`	`QUOTEZ_LOG_LEVEL`	`INFO`	Protokollierungsschwelle. Aufzeichnungen gehen immer nach stderr, weil stdout der Draht ist

Verbinden mit einem Host

Die Hosts sind sich über den Konfigurationsschlüssel nicht einig, und mcpServers versus servers falsch zu setzen, ist der übliche Grund, warum ein Server nie erscheint.

Host	Datei	Schlüssel
Claude Desktop	`~/Library/Application Support/Claude/claude_desktop_config.json` auf macOS, `%APPDATA%\Claude\claude_desktop_config.json` auf Windows	`mcpServers`
Cursor	`.cursor/mcp.json`	`mcpServers`
VS Code	`.vscode/mcp.json`	`servers`, und fügen Sie `"type": "stdio"` neben `command` hinzu
Claude Code	keine Datei, CLI verwenden	`claude mcp add quotez -- uv tool run --from git+https://github.com/PNX89/QUOTEZ quotez --source replay`

{
  "mcpServers": {
    "quotez": {
      "command": "/absolute/path/to/uv",
      "args": ["tool", "run", "--from", "git+https://github.com/PNX89/QUOTEZ",
               "quotez", "--source", "replay"]
    }
  }
}

command muss der absolute Pfad von which uv sein. Ein Host startet den Server mit einem nahezu leeren PATH, daher ist ein bloßes uv der mit Abstand häufigste Grund, warum ein Server stillschweigend keine Verbindung herstellt.

Tools

Acht Tools, in dieser Reihenfolge registriert, was der Reihenfolge von tools/list entspricht; Clients cachen diese Liste, daher ist die Reihenfolge absichtlich festgelegt. Eine Ressource, symbols://list, liefert dasselbe Instrumentenuniversum als application/json.

Tool	Argumente	Rückgabe	Zugriff	Wiedergabequelle	MetaTrader-Quelle
`list_symbols`	`group` optional, MetaTrader-Gruppensyntax	`SymbolList`	lesen	4 generierte Instrumente	`symbols_get(group=...)`
`get_quote`	`symbol`	`Quote`	lesen	abgeleitet vom letzten gespeicherten Balken	`symbol_info_tick`
`get_bars`	`symbol`, `timeframe`, `count` (1 bis 5000, begrenzt durch `--max-bars`)	`BarSeries`	lesen	M1 lokal hochaggregiert	`copy_rates_from_pos`
`get_bars_range`	`symbol`, `timeframe`, `start`, `end`	`BarSeries`	lesen	M1 lokal hochaggregiert	`copy_rates_range`
`symbol_info`	`symbol`	`SymbolSpec`	lesen	aus `symbols.json`	`symbol_info`
`get_account`	keine	`Account`	lesen	Platzhalterzahlen, `synthetic: true`	`account_info`, Login maskiert
`list_positions`	keine	`PositionList`	lesen	immer leer	`positions_get`
`list_orders`	keine	`OrderList`	lesen	immer leer	`orders_get`

list_symbols verwendet MetaTraders eigene Gruppensyntax anstatt eine eigene zu erfinden: *-Platzhalter am Anfang und Ende eines Musters, kommagetrennte Bedingungen und ! zur Negation einer Bedingung. Einschlüsse müssen vor Ausschlüssen kommen, also ist "*, !*USD*" alles außer den USD-Instrumenten, während "!*USD*, *" alles abdeckt. Mt5Source übergibt die Zeichenkette an symbols_get; die Wiedergabequelle führt dieselbe Syntax durch quotez.groups aus, sodass beide einen Filter identisch beantworten.

Jedes Tool gibt ein Pydantic-Modell zurück, sodass das SDK ein outputSchema aus der Rückgabeannotation ableitet, structuredContent füllt und die Nutzlast validiert, bevor sie den Server verlässt. Ein BaseModel wird unverpackt verwendet, weshalb get_bars ein Objekt mit einem bars-Schlüssel zurückgibt, anstatt {"result": ...}.

Wie es funktioniert

flowchart LR
    host["MCP host<br/>Claude Desktop, Cursor, VS Code"]
    server["quotez.server<br/>8 tools, 1 resource"]
    proto["MarketDataSource<br/>Protocol"]
    replay["ReplaySource<br/>bundled CSVs, any OS"]
    mt5["Mt5Source<br/>Windows only, lazy import"]
    term["MetaTrader 5 terminal"]
    host -- "JSON-RPC over stdio" --> server
    server --> proto
    proto --> replay
    proto --> mt5
    mt5 -- "read calls only" --> term

MarketDataSource ist die Nahtstelle, gegen die der gesamte Server geschrieben ist. Nichts darüber importiert MetaTrader5, und Mt5Source löst die Erweiterung innerhalb eines privaten Helfers beim ersten Gebrauch auf, nicht beim Modulimport, sodass import quotez funktioniert, wo kein Rad existiert. Das macht ReplaySource zu einer erstklassigen Implementierung anstelle eines Mocks: Die Toolschicht kann die beiden nicht unterscheiden, sodass die gesamte Suite den echten Codepfad ohne installiertes Terminal durchläuft.

Die gebündelten Daten sind vier generierte Instrumente (SYNTH_FX_ALPHA, SYNTH_FX_BETA, SYNTH_IDX_GAMMA, SYNTH_MTL_DELTA), jeweils 3600 M1-Balken, 08:00 bis 14:00 UTC an Wochentagen vom 01.06.2026 bis 12.06.2026, mit neun Sitzungsunterbrechungen, acht über Nacht und eine über ein Wochenende, denn eine lückenlose Serie ist die Serie, die einen Aggregationsfehler verbirgt. scripts/generate_replay_data.py hat die Dateien einmalig aus einem gesetzten random.Random erstellt und die Ausgabe ist eingecheckt. CSVs werden über importlib.resources gelesen, nie über Path(__file__).parent, was in einem Checkout funktioniert und unter der gezippten Installation, die uvx durchführt, bricht.

Tools und Ressourcen sind nicht dasselbe

Ein Tool ist das, was das MODELL aufzurufen entscheidet; eine Ressource ist das, was die ANWENDUNG zu laden entscheidet. get_bars ist modellgesteuert: Es wählt mitten in der Argumentation ein Symbol, einen Zeitrahmen und eine Anzahl aus. symbols://list ist anwendungsgesteuert: Ein Host heftet das Universum einmalig in den Kontext, bevor das Modell irgendetwas entschieden hat. Deshalb ist es keine beiläufige Duplizierung von list_symbols, einer gefilterten Suche, die das Modell absichtlich ausführt.

Die offensichtliche nächste Ressource, bars://{symbol}/{timeframe}, wurde bewusst nicht gebaut: Sie dupliziert get_bars für dieselben Daten, und ein URI mit Platzhaltern ist eine Ressourcenvorlage, die resources/list für resources/templates/list verlässt und von vielen Hosts schlecht oder gar nicht dargestellt wird. Ein Test stellt sicher, dass keine Ressourcenvorlagen registriert sind.

Zeitrahmenaggregation

Die Wiedergabequelle speichert einen Basiszeitrahmen, M1, und quotez.aggregate aggregiert M5, M15, M30, H1, H4 und D1 daraus hoch. Eine gespeicherte Kopie, eine Hochaggregation, eigenständig testbar, was wichtig ist, weil seine Fehlerart still ist: Eine falsche Aggregation liefert auf unbestimmte Zeit plausible Zahlen und löst nie eine Ausnahme aus.

Die MetaTrader-Quelle aggregiert nichts hoch. Ein Terminal enthält bereits jeden Zeitraum, daher wird es direkt nach dem Zeitrahmen gefragt; eine erneute Ableitung aus M1 wäre langsamer und würde von den Diagrammen abweichen, die der Bediener geöffnet hat. Die beiden Quellen beantworten daher denselben Aufruf bei D1, H4 und spread geringfügig unterschiedlich, was in den Einschränkungen steht und nicht Ihnen überlassen wird, herauszufinden.

Die Invarianten der Hochaggregation, von denen jede ein Testname ist:

M1 ist der einzige Basis-Zeitrahmen. Alles Gröbere wird daraus abgeleitet.
Buckets sind Wanduhrzeit, berechnet durch Ganzzahldivision der Epochensekunde, niemals durch gruppenweise Anordnung von N Zeilen.
Ziele sind ganzzahlige Vielfache von 60 Sekunden. Alles andere löst InvalidRequest aus.
OHLC ist erster Eröffnungskurs, maximaler Höchstkurs, minimaler Tiefstkurs, letzter Schlusskurs.
tick_volume wird summiert. spread nicht: Es ist eine zeitpunktbezogene Eigenschaft eines Quotes, daher meldet ein aggregierter Balken null.
Balken werden nach ihrem linken Rand in UTC bezeichnet.
Ein unvollständiger nachlaufender Bucket wird verworfen, anstatt als Teilbalken ausgegeben zu werden. Ein Bucket wird nur dann ausgegeben, wenn die Eingabe einen Balken zu oder nach dem Ende dieses Buckets enthält.
Leere Eingabe gibt eine leere Liste zurück.

Invariante 2 verdient ihre Tests. Gruppierung nach Position stimmt mit der Wanduhr-Bucketbildung bei einer lückenlosen Serie überein und weicht ab, sobald eine Lücke auftritt: Die Gruppierung von 360 Balken-Sitzungen in Vierergruppen setzt den Schlusskurs von Freitag und den Eröffnungskurs von Montag in einen Balken und nennt ihn eine Vier-Stunden-Kerze. Invariante 7 ist ihr Gegenstück, denn das Ende einer Sitzung ist nicht dasselbe Ereignis wie das Ausgehen der Daten.

Sicherheitsdesign

Die Behauptung ist strukturell, nicht konfigurierbar. Diese Codebasis enthält keinen Schreibpfad. Es gibt kein order_send, kein order_check, kein symbol_select, keine MarketWatch-Mutation und keinen Dateischreibvorgang irgendwo in src/quotez/. Keine Konfiguration kann einen Schreibvorgang aktivieren, weil es nichts zu aktivieren gibt.

Zwei Tests stellen dies sicher, und der zweite ist der, der etwas bedeutet. Der erste durchsucht das Paket nach diesen drei MetaTrader-Aufrufen: günstig, deckt jede Datei ab und wird durch einen zur Laufzeit zusammengesetzten Namen erfüllt. Der zweite durchläuft den AST von mt5source.py und behauptet stattdessen die positive Eigenschaft, dass die Menge der Attribute, die dieses Paket vom Terminalmodul liest, genau die Leseaufrufe sind, die sein eigenes Docstring nennt, plus die sieben Zeitrahmenkonstanten, ohne dass etwas über getattr erreicht und ohne dass etwas an eine zweite Variable gebunden wird. _mt5() gibt das gesamte MetaTrader5-Modul zurück, daher beweist das Fehlen von drei Namen unter mehreren hundert Attributen für sich genommen sehr wenig. Fünf absichtlich defekte Code-Schnipsel werden gegen diesen Durchlauf geprüft, sodass bekannt ist, dass der Durchlauf selbst fehlschlägt, wenn er sollte.

Jedes Tool wird mit ToolAnnotations(read_only_hint=True, open_world_hint=False) deklariert. Diese Deklaration ist eine Höflichkeit gegenüber Clients und nichts weiter: Die MCP-Spezifikation teilt Clients mit, Tool-Annotationen als nicht vertrauenswürdig zu behandeln, es sei denn, sie stammen von einem vertrauenswürdigen Server. read_only_hint=True beschreibt das Tool, es schränkt den Client nicht ein, und die Eigenschaft, die ein Prüfer überprüfen kann, ist das Fehlen der Aufrufe und nicht das Vorhandensein des Flags. Übertragen auf die eigenen Sicherheitsüberlegungen für Tools der Spezifikation, einschließlich der Anforderung, die dieser Server nicht erfüllt:

Spezifikationsanforderung	QUOTEZ	Wo
Alle Tool-Eingaben validieren	Ja	JSON Schema abgeleitet von den Typannotationen, `Literal`-Zeitrahmen, `Field(ge=1, le=5000)` auf `count`, plus Laufzeitprüfungen in den Handlern
Angemessene Zugriffskontrollen implementieren	Ja	Die Symbol-Whitelist wird auf jedes Tool und auf die Ressource angewendet, nicht nur auf die Getter
Tool-Aufrufe ratenbegrenzen	Nein	nicht implementiert und in den Einschränkungen aufgeführt. Ein Stdio-Server ist ein Kindprozess genau eines Hosts, daher obliegt die Ratenbegrenzung dem Host
Tool-Ausgaben bereinigen	Ja	Der Kontologin wird auf die letzten vier Ziffern maskiert, die Namen von Broker, Server und Kontoinhaber werden nie zurückgegeben, und `synthetic` ist ein Pflichtfeld in jeder Nutzlast

Ein blockiertes Symbol wird als SymbolNotFound mit der Meldung gemeldet, die ein Tippfehler erhalten würde: „Symbol 'X' ist auf diesem Server nicht verfügbar.“ Ein eindeutiges „nicht erlaubt“ würde die Whitelist zu einem Entdeckungsorakel für Instrumente machen, die ein Betreiber nicht offenlegen wollte.

Fehler nehmen einen von zwei Kanälen, ausgewählt danach, ob ein intelligenteres Modell den Fehler hätte vermeiden können. Ein falsch geschriebenes Symbol könnte das, daher sind SymbolNotFound und InvalidRequest gewöhnliche Ausnahmen, die zu Tool-Fehlern werden, die das Modell lesen und erneut versuchen kann. Ein Terminal, das nicht läuft, könnte das nicht, daher wird SourceUnavailable als MCPError ausgelöst, ein Protokollfehler ohne jegliches Ergebnis. Nichts hier gibt einen Fehlerstring zurück: Ein zurückgegebener String trägt is_error=False und wird als erfolgreiche Antwort gelesen. Ein Test ruft jedes Tool mit schlechter Eingabe auf und behauptet das Flag.

Designentscheidungen

mcp>=2.0.0,<3 und MCPServer, nicht der v1-Pin und FastMCP. Das SDK bietet immer noch mcp>=1.28,<2 für Leute, die noch nicht migriert haben, aber ein Server aus der v1-Ära verrät sich in drei Sekunden: from mcp.server.fastmcp import FastMCP. Die Migrationsanleitung enthält die Umbenennungen. Der Low-Level-Server war die Alternative und umschließt Rückgabewerte nicht mehr automatisch, was bedeutet hätte, JSON Schema für acht Tools von Hand zu schreiben.

Typisierte Pydantic-Rückgaben, keine Textblobs. Die meisten öffentlichen MCP-Server geben Prosa zurück und überlassen dem Modell das Parsen. Hier ist die Rückgabeannotation das Ausgabeschema, daher kostet Typisierung nichts und bringt Validierung, bevor die Nutzlast den Server verlässt.

Zwei Balken-Tools, nicht eines mit optionalen Argumenten. JSON Schema kann keine gegenseitige Ausschließlichkeit ausdrücken, daher würde ein einzelnes get_bars(count or start..end) „entweder oder, aber nicht beides“ als Prosa auf das Modell abwälzen. Zwei Tools haben zwei vollständig gültige Schemata, und die Fehlerklasse „beide angegeben, keins angegeben“ existiert nicht mehr.

Generierte Daten, kein echter Feed. Eine Lizenzentscheidung, keine Präferenz. MetaTrader-Exporte sind der lizenzierte Feed des Brokers, und bei Index- und Aktien-CFDs ist der Basiswert börsenlizenziert. Yahoos Hilfeseiten geben die Einschränkung in klaren Worten an: Sie dürfen Informationen, die auf Yahoo Finance angezeigt oder von Yahoo Finance bereitgestellt werden, nicht weiterverbreiten, und seine Entwickler-API-Bedingungen schränken den Verkauf oder die Unterlizenzierung des Zugriffs separat ein. HistDatas FAQ gewährt überhaupt keine Weiterverbreitungsrechte; es heißt nur, dass die Daten ohne Gewährleistung kommen, und Schweigen ist keine Lizenz. Das Einchecken davon in ein MIT-Repository würde Daten neu lizenzieren, die ich nicht neu lizenzieren darf.

Die Standardbibliothek, nicht pandas oder numpy. Bei gebündeltem CSV-Maßstab reichen csv plus datetime plus Datenklassen aus, und der Baum bleibt prüfbar. Dieser Baum verdient es jedoch, ehrlich benannt zu werden, alles davon: mcp 2.x ist eine direkte Abhängigkeit, die anyio, httpx2, jsonschema, mcp-types, opentelemetry-api, pydantic, pyjwt mit seinem Crypto-Extra, python-multipart, sse-starlette, starlette, typing-extensions, typing-inspection und uvicorn mitbringt, plus pywin32 unter Windows. Das Crypto-Extra bringt cryptography, cffi und pycparser dahinter mit. Das ist ein größerer Fußabdruck als v1, und ein Test liest das eingecheckte uv.lock und schlägt fehl, wenn diese Liste nicht mehr damit übereinstimmt, denn ein Absatz, der existiert, um den Baum zu benennen, ist nichts wert, wenn er den größten Teil des Baums nicht benennt.

Kein run_backtest-Tool. Ein Backtest ist rechenzeitlich unbegrenzt, benötigt weit mehr als eine MarketDataSource und würde QUACKZ duplizieren, daher würde das Paar wie zwei halbe Projekte statt zwei fokussierte wirken. Aus demselben Grund sind die Leitplanken hier domänenlokal: Eingabevalidierung, begrenzte Abfragen, ein festes Instrumentenuniversum, keine Nebenwirkungen. Allgemeine Agenten-Leitplanken gehören in QUELLZ, nicht fünfmal neu erfunden.

Einschränkungen

Kein Continuous-Integration-Runner übt den Live-MetaTrader-Pfad aus, nirgendwo. Es gibt kein Nicht-Windows-Rad und kein Runner hat ein Terminal oder ein Brokerkonto. Der Windows-Job beweist, dass die Erweiterung importiert wird und dass Mt5Source ein fehlendes Terminal sauber meldet, und das ist alles. Die Feldzuordnung von Mt5Source ist der am wenigsten getestete Code hier, abgedeckt durch Fake-Modul-Tests.
MetaTrader5 ist nur für Windows und veröffentlicht keine Quellverteilung, daher ist pip install quotez[mt5] auf macOS und Linux absichtlich ein No-Op. Ein Test stellt sicher, dass der Umgebungsmarker dies so beibehält.
initialize() startet das Terminal, falls es nicht bereits läuft, und die gesamte Operation wird durch sein timeout-Argument begrenzt, das standardmäßig auf 60000 Millisekunden dokumentiert ist. Die Seite gibt keine Zahl für den Start selbst an, daher behandeln Sie 60 Sekunden als Obergrenze für den Aufruf und nicht als gemessene Startzeit. QUOTEZ öffnet die Verbindung einmal in der Serverlebensdauer und nicht pro Aufruf, daher landet das, was es kostet, beim Start, anstatt den ersten Tool-Aufruf wie aufgehängt aussehen zu lassen.
Die beiden Quellen stimmen nicht darin überein, wo ein D1- oder H4-Bucket beginnt. Der Replay-Rollup rundet auf die Epochensekunde ab, daher öffnet D1 um 00:00 UTC und H4 um 00, 04, 08, 12, 16 und 20 UTC. Ein MetaTrader-Terminal richtet D1 und H4 am Broker-Server-Tag aus, der üblicherweise UTC+2 oder UTC+3 ist, daher gibt derselbe get_bars(symbol, "D1") eine Kerze mit einer anderen Eröffnungszeit und anderen OHLC zurück, je nachdem, welche Quelle konfiguriert ist. Nichts hier resampelt das M1 des Terminals, um dies zu verbergen, denn ein Balken, der vom eigenen Chart des Betreibers abweicht, ist schlimmer als ein dokumentierter Offset.
Aus demselben Grund ist spread bei jedem Replay-Balken über M1 null und bei jedem MetaTrader-Balken gesetzt. Der Rollup löscht es absichtlich; das Terminal meldet seinen eigenen Wert für jeden Zeitrahmen und QUOTEZ gibt ihn weiter, anstatt Daten zu verwerfen, die die Quelle geliefert hat.
copy_rates_from_pos und copy_rates_range werden stillschweigend durch die Einstellung „Max. Balken im Chart“ des Terminals begrenzt, daher kann eine Anfrage innerhalb der eigenen Obergrenze des Servers dennoch zu kurz kommen, und nichts in der MetaTrader-API sagt dies.
get_bars überspringt den Balken, den das Terminal noch aufbaut, daher ist sein neuester Balken immer geschlossen. get_bars_range tut dies nicht, weil die Grenzen die des Aufrufers sind: Ein end innerhalb des aktuellen Intervalls gibt den Teilbalken dieses Intervalls zurück.
symbol_info() gibt None zurück für ein unbekanntes Symbol, anstatt eine Ausnahme auszulösen, ebenso wie symbols_get() bei einem Fehler. Jede Aufrufstelle hier prüft dies, aber das ist die Form der umschlossenen API.
MetaTrader speichert Balken- und Tick-Zeiten in UTC ohne Verschiebung, während ein naives Python-datetime gegen die lokale Zone auflöst; die Dokumentation zu copy _rates _range sagt dies. Jeder ausgehende Zeitstempel wird mit tz=UTC erstellt und naive Eingaben werden abgelehnt, aber dies ist die Falle, die eine ganze Serie stillschweigend um eine Stunde verschiebt.
Keine Ratenbegrenzung. Ein Stdio-Server ist ein Kindprozess eines Hosts, und der Host besitzt diese.
Die Replay-Daten sind im Beispielmaßstab und generiert: 4 Instrumente, jeweils 3600 M1-Balken, zehn Handelstage. Sie demonstrieren die Tools und üben die Aggregation, und sie sind weder ein Forschungsdatensatz noch ein Markt.
Version 0.1.0 ist schreibgeschützt und nur Stdio, ohne Prompts-Fähigkeit, ohne SSE oder streamable HTTP-Transport und ohne OAuth.

Warum ich dies gebaut habe

Ich führe Walk-Forward-Forschung mit Indexdaten durch und habe MetaTrader-Terminals für die FX- und Metallseite parat, also waren beide Hälften bereits auf meinem Schreibtisch. Was mich dazu brachte, dies zu schreiben, war die Beobachtung, wie ein Agent eine Zahl aus einem schlecht getippten Tool als Tatsache wiederholte, ohne Einheit, ohne Zeitzone und ohne Angabe, woher sie stammte. Bei Marktdaten ist das nicht kosmetisch: Ein Balken, der nach seinem Schlusskurs statt nach seinem Eröffnungskurs benannt ist, oder ein Zeitstempel, der stillschweigend in die Ortszeit verschoben wurde, liefert eine Antwort, die richtig aussieht, aber um eine Stunde daneben liegt. Dabei handelt es sich also hauptsächlich um Entscheidungen über Herkunft und darüber, was ein Tool behaupten darf, eingewickelt in einen kleinen Aggregationscode.

Entwicklung

uv sync --dev
uv run pytest
uv run ruff check .
uv run ruff format --check .
uv run mypy

251 Tests, kein Netzwerk, ein paar Sekunden, und identisch auf macOS, Linux und Windows. Diese Anzahl wird gegen einen echten Collection-Lauf geprüft, denn eine Zahl in einer README ist eine Zahl, die niemand aktualisiert.

Lizenz

MIT. Siehe LICENSE.

Teil des Q...Z-Toolsets, fünf Tools für das Versagen, das sich nicht ankündigt:

QUACKZ, das einen Backtest entlarvt, der nur gut aussieht, weil er aus zweihundert ausgewählt wurde.
QUOTEZ, dieses hier: Marktdaten, die ein Agent lesen, aber nicht darauf handeln kann.
QUELLZ, misst, was Prompt-Injection-Eindämmung sowohl an Nutzen als auch an Angriffsrate kostet.
QUIDZ, verweigert die ausgehende Zahlung, die zweimal rausgegangen wäre.
QUESTZ, stoppt einen Scraper, bevor er ein CSV von einer Seite schreibt, die ihre Form geändert hat.

Available Tools

8 tools

get_accountGet account stateA

Read-only

Return the connected account's balance, equity, margin and leverage.

The login is masked to its last four digits and the broker, server and account holder names are never returned. On the replay source these figures are invented placeholders describing no real account: the payload carries synthetic=true, the currency is SYN and the login is ****0000. Do not restate them as a real balance.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
`equity`	Yes	Balance plus floating profit and loss.
`margin`	Yes	Margin currently in use.
`source`	Yes	Data source that produced these figures.
`balance`	Yes	Balance, excluding floating profit and loss.
`currency`	Yes	Account deposit currency.
`leverage`	Yes	Account leverage, for example 100 for 1:100.
`synthetic`	Yes	True when the figures are generated. The replay source always sets this, and its balance and equity are invented placeholders that describe no real account.
`margin_free`	Yes	Margin available for new positions.
`login_masked`	Yes	Account login masked to its last four digits. The full login is never returned.
`margin_level`	Yes	Equity divided by margin, as a percentage.

TDQS

A4.5/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description discloses key behavioral traits beyond annotations: login masking, omission of broker/server/account holder names, and synthetic data indicators on replay. This adds significant value over the readOnlyHint and openWorldHint annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three sentences long, front-loaded with the main purpose, and every sentence adds essential information. There is no redundancy or wasted language.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has no parameters and an output schema exists, the description adequately covers the return values and adds critical context about data masking and synthetic mode. It is complete for an agent to understand and invoke the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has no parameters and schema coverage is 100%, so the baseline is 3. The description does not add meaning to any parameters because there are none to explain; it appropriately focuses on the tool's output and behavior.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Return' and the specific resource 'connected account's balance, equity, margin and leverage'. This distinguishes it from sibling tools like list_symbols, get_quote, and get_bars, which operate on different data.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context about when the tool returns synthetic data on the replay source and warns against restating it as real. It does not explicitly contrast with siblings, but the context is sufficient for an agent to understand when to use this tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_barsGet recent barsA

Read-only

Return the most recent OHLCV bars for a symbol, oldest first.

Times are UTC and label each bar's OPEN, the left edge of the interval it covers. count is capped by the server (see the server instructions for the current limit); ask for a coarser timeframe rather than more bars. The bar that is still forming is never returned, so the newest bar is always a closed one; call get_quote for the current price. An unknown or unavailable symbol returns a tool error naming the symbol; call list_symbols first if unsure. On the replay source the prices are generated, not recorded from any market.

ParametersJSON Schema

Name	Required	Description
`count`	No	How many of the most recent bars to return, newest last.
`symbol`	Yes	Instrument name exactly as list_symbols spells it.
`timeframe`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`bars`	Yes	The bars, oldest first.
`count`	Yes	Number of bars returned.
`source`	Yes	Data source that produced these bars.
`symbol`	Yes	Symbol these bars belong to.
`synthetic`	Yes	True when the prices are generated, not observed.
`timeframe`	Yes	Timeframe of each bar.

TDQS

A4.9/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description discloses critical behavioral traits beyond annotations: bars are in UTC labeling the open, the newest bar is always closed (never returns forming bar), the server caps count, and on replay source prices are generated (not recorded). The readOnlyHint annotation is consistent with the read-only nature described, and no contradiction exists.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise (5 sentences) and front-loaded: first sentence states the core purpose and ordering. Every sentence adds distinct value (timezone, counting strategy, bar state, error handling, data source). No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has 3 parameters, an output schema (present), and annotations (readOnlyHint, openWorldHint), the description covers all necessary context: purpose, parameters, error handling, alternatives, and data source behavior. The output schema likely describes return format, so no need to explain return values. Complete for a moderately complex tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 67% (only 2 of 3 parameters have descriptions). The description adds value: clarifies that 'count' is capped by server ('ask for a coarser timeframe rather than more bars'), that 'symbol' must match list_symbols spelling, and that 'timeframe' is the interval length. The description compensates for the missing schema description on 'timeframe' by listing enum values contextually (M1, M5, etc.) and implying the left-edge labeling. However, it doesn't explain the 'timeframe' enum beyond listing intervals, so a 4 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool returns 'the most recent OHLCV bars for a symbol, oldest first'. It identifies the specific verb (return), resource (OHLCV bars), and ordering (oldest first), distinguishing it from siblings like get_quote (current price) and get_bars_range (range-based).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit guidance: when to use alternatives ('call get_quote for the current price'), when to call list_symbols first ('call list_symbols first if unsure'), how to handle timeframes ('ask for a coarser timeframe rather than more bars'), and error handling ('An unknown or unavailable symbol returns a tool error naming the symbol'). It also notes the 'count' cap and server limit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_bars_rangeGet bars in a date rangeA

Read-only

Return the OHLCV bars whose open time falls in [start, end), oldest first.

Both bounds must carry a UTC offset, for example 2026-06-01T08:00:00Z. start is inclusive and end is exclusive, so consecutive ranges tile without repeating a bar. The number of bars the range spans is capped by the same limit that applies to get_bars, so a wide window at a fine timeframe returns a tool error asking for a coarser one rather than a truncated answer. Unlike get_bars, an end that reaches into the interval currently forming can return that bar, because the bounds are yours; stop end at a closed interval if that matters. On the replay source the prices are generated, not recorded from any market.

ParametersJSON Schema

Name	Required	Description
`end`	Yes	Exclusive, ISO 8601, UTC.
`start`	Yes	Inclusive, ISO 8601, UTC.
`symbol`	Yes	Instrument name exactly as list_symbols spells it.
`timeframe`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`bars`	Yes	The bars, oldest first.
`count`	Yes	Number of bars returned.
`source`	Yes	Data source that produced these bars.
`symbol`	Yes	Symbol these bars belong to.
`synthetic`	Yes	True when the prices are generated, not observed.
`timeframe`	Yes	Timeframe of each bar.

TDQS

A4.7/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description goes well beyond the readOnlyHint annotation, explaining the inclusive/exclusive bounds, UTC offset requirement, tiling behavior, error on exceeding limits, the nuance with forming bars, and the synthetic nature of replay data. This gives the agent a full behavioral model.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose, and every subsequent sentence adds essential behavioral or usage detail. It is concise given the complexity, with no redundant wording.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers not only the basic operation but also edge cases like limit-caused errors, the difference from get_bars, data source caveat, and formatting requirements. Given the output schema exists, return values need no explanation, and the description is fully sufficient for an agent to invoke the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already covers 75% of parameters with descriptions, but the description adds critical semantics for start/end (inclusive/exclusive, UTC offset, example format) and clarifies the meaning of range-related behavior beyond the schema. Timeframe is only an enum, but the values are self-explanatory.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool returns OHLCV bars within a half-open date range, ordered oldest first. The title 'Get bars in a date range' plus the explicit interval notation [start, end) distinguishes it from its sibling get_bars.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description references get_bars multiple times, noting the same limit applies and highlighting a key difference regarding forming bars. This provides clear comparative context, though it does not include a direct 'use this when' statement or explicit when-not-to-use guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_quoteGet a quoteA

Read-only

Return the latest bid, ask and spread in points for one instrument.

The time is UTC. On the replay source it is the last stored bar's open time rather than the current clock, so the answer is reproducible and is NOT a live market price. An unknown or unavailable symbol returns a tool error naming the symbol; call list_symbols if unsure.

ParametersJSON Schema

Name	Required	Description	Default
`symbol`	Yes	Instrument name exactly as list_symbols spells it.

Output Schema

ParametersJSON Schema

Name	Required	Description
`ask`	Yes	Best ask price.
`bid`	Yes	Best bid price.
`time`	Yes	Quote time in UTC. On the replay source this is the last stored bar's open time, never the wall clock.
`source`	Yes	Data source that produced this quote.
`symbol`	Yes	Symbol this quote belongs to.
`synthetic`	Yes	True when the price is generated, not observed.
`spread_points`	Yes	Ask minus bid, expressed in points.

TDQS

A4.5/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description discloses crucial behavior beyond the annotations: 'On the replay source it is the last stored bar's open time rather than the current clock, so the answer is reproducible and is NOT a live market price.' It also details error handling for unknown symbols. This adds significant context for an agent deciding whether to trust the result as live.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two short sentences plus a crucial behavioral note. Every sentence adds value, and the key action ('Return...') is front-loaded. No redundant or vague language. It is concise without omitting necessary information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (one required parameter, no nested types) and the existence of an output schema (not shown but indicated in context signals), the description adequately covers the return value, time source, error behavior, and a pointer to list_symbols. It is complete for an agent to use correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% coverage for its single parameter 'symbol', with description 'Instrument name exactly as list_symbols spells it.' The tool description does not add new semantic meaning; it only repeats the schema's point about exact spelling. Baseline 3 is appropriate when schema already fully documents the parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Return the latest bid, ask and spread in points for one instrument.' The verb 'return' and resource 'quote for one instrument' are specific. It implicitly distinguishes from sibling tools like get_bars (historical bars) and list_symbols (listing symbols).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit guidance: 'An unknown or unavailable symbol returns a tool error naming the symbol; call list_symbols if unsure.' This tells the agent when to use list_symbols instead. It does not explicitly state when not to use this tool (e.g., for historical prices use get_bars), but the sibling context and the mention of 'latest' imply the appropriate use case.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_ordersList pending ordersA

Read-only

Return every pending order, with its type, volumes and trigger price.

Read only: this server can place, modify and cancel nothing. On the replay source the list is always empty and the payload carries synthetic=true.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
`count`	Yes	Number of pending orders.
`orders`	Yes	The pending orders.
`source`	Yes	Data source that produced this list.
`synthetic`	Yes	True when the orders are generated, not real.

TDQS

A4.1/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already mark readOnlyHint=true. The description reinforces this with 'this server can place, modify and cancel nothing' and adds critical context about the replay source (list always empty, synthetic flag). This goes beyond what annotations provide, though it does not cover all possible behavioral traits (e.g., rate limits, auth needs).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three sentences, each earning its place: purpose, read-only assertion, and replay-specific behavior. No unnecessary words, front-loaded with the core action.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has no parameters and an output schema exists. The description covers return fields and a key behavioral detail about replay sources, making it fully adequate for the low complexity of this tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With zero parameters and 100% schema coverage, the description need not add parameter-level meaning. It correctly describes the output fields but not parameter semantics; baseline 3 is appropriate as the schema carries the full load.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Return' and the resource 'every pending order', and specifies the data included (type, volumes, trigger price). It differentiates from sibling tools which deal with symbols, quotes, bars, account, and positions, leaving no ambiguity about what this tool does.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for retrieving pending orders and includes the read-only note, but does not explicitly say when to use this tool over alternatives like list_positions. It lacks mentions of conditions under which the tool should or should not be used, nor does it reference sibling tools for comparison.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_positionsList open positionsA

Read-only

Return every open position, with entry price, current price and floating profit.

Read only: this server can open, modify and close nothing. On the replay source the list is always empty and the payload carries synthetic=true.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
`count`	Yes	Number of open positions.
`source`	Yes	Data source that produced this list.
`positions`	Yes	The open positions.
`synthetic`	Yes	True when the positions are generated, not real.

TDQS

A4.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and openWorldHint=false. The description adds value beyond annotations by stating the server can 'open, modify and close nothing', and explains the synthetic flag behavior on replay sources. This provides meaningful behavioral context without contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two short sentences, each providing essential information. No filler or redundancy. Perfectly sized for a tool with no parameters and clear purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no parameters and an output schema present, the description is largely complete. It explains the tool's purpose, return fields, and special behavior (read-only, synthetic flag on replay). One minor gap: it doesn't mention whether the list is always empty in certain modes beyond replay.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has no parameters, so the description has no responsibility to document parameters. With 0 parameters and 100% schema coverage, the description adds value by explaining return fields (entry price, current price, floating profit), which aids correct invocation and interpretation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Return') and resource ('open position'), and lists the fields returned (entry price, current price, floating profit). It clearly distinguishes this tool from siblings like `list_symbols` and `list_orders`.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description clarifies that the tool is read-only and explains behavior on replay sources (always empty, payload has synthetic=true). However, it doesn't explicitly state when to use this tool over alternatives like `get_account` or `list_orders`, though the purpose is clear enough.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_symbolsList instrumentsA

Read-only

Return every instrument this server exposes, with its digits and point size.

Call this before anything else: it is the only authoritative list of symbol names, and a name that is not in it produces a tool error everywhere else. The optional group filter uses MetaTrader's own syntax, described in the argument. On the replay source the instruments are generated and the payload carries synthetic=true.

ParametersJSON Schema

Name	Required	Description	Default
`group`	No	Optional filter. MetaTrader group syntax: '' wildcards at the start and end of a pattern, several comma separated conditions, and '!' to negate one. Inclusions must come before exclusions, so ", !USD" is everything except the USD instruments while "!USD, *" matches everything.

Output Schema

ParametersJSON Schema

Name	Required	Description
`count`	Yes	Number of instruments returned.
`source`	Yes	Data source that produced this list.
`symbols`	Yes	The instruments, in source order.
`synthetic`	Yes	True when the instruments are generated, not real.

TDQS

A4.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true (safe read) and openWorldHint=false (closed set). The description adds value by noting that missing symbols cause errors in other tools, and that replay sources return synthetic=true. This complements the annotations without contradicting them.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three sentences with zero wasted words. Each sentence serves a distinct purpose: stating the return value, explaining when to call and consequences, and describing the optional filter. Information is front-loaded with the core purpose first.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (1 optional parameter, read-only, closed set), output schema exists, and annotations are clear, the description is fully complete. It covers purpose, usage guidance, parameter behavior, and edge cases (replay vs. live), leaving no gaps for an agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and already documents the group parameter syntax thoroughly. The description reinforces this by referencing the syntax explanation in the argument description, adding the context of how the filter interacts with the overall tool purpose, which is helpful for an agent.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool returns 'every instrument this server exposes, with its digits and point size'. It uses a specific verb ('Return') and resource ('every instrument'), and distinguishes itself from siblings like get_quote and symbol_info by positioning itself as the authoritative source of symbol names.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly advises 'Call this before anything else', warns that missing names cause errors elsewhere, explains the optional group filter's syntax, and clarifies behavior differences on replay sources. No alternative tools are needed for this purpose, and it sets clear prerequisites for using other tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

symbol_infoGet contract specificationA

Read-only

Return the contract specification for one instrument.

Digits and point size for rounding prices, current spread, minimum stop distance, tick value and size, contract size, the tradable volume range, and the base, profit and margin currencies. Field names are MetaTrader's own. An unknown or unavailable symbol returns a tool error naming the symbol. On the replay source the instrument is generated and the payload carries synthetic=true.

ParametersJSON Schema

Name	Required	Description	Default
`symbol`	Yes	Instrument name exactly as list_symbols spells it.

Output Schema

ParametersJSON Schema

Name	Required	Description
`name`	Yes	Symbol name.
`point`	Yes	Value of one point, the smallest price step.
`digits`	Yes	Decimal places in a quoted price.
`source`	Yes	Data source that produced this specification.
`spread`	Yes	Current spread in points.
`synthetic`	Yes	True when the instrument is generated, not real.
`volume_max`	Yes	Largest tradable volume, in lots.
`volume_min`	Yes	Smallest tradable volume, in lots.
`description`	Yes	Human readable instrument name.
`volume_step`	Yes	Volume increment, in lots.
`spread_float`	Yes	True when the broker quotes a floating spread.
`currency_base`	Yes	Base currency of the instrument.
`currency_margin`	Yes	Currency the margin is charged in.
`currency_profit`	Yes	Currency the profit is denominated in.
`trade_tick_size`	Yes	Smallest price change, in price units.
`trade_tick_value`	Yes	Profit in the account currency from a one tick move on one lot.
`trade_stops_level`	Yes	Minimum distance in points between price and a stop or limit order.
`trade_freeze_level`	Yes	Distance in points within which orders are frozen and cannot be changed.
`trade_contract_size`	Yes	Units of the base asset in one lot.

TDQS

A4.3/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, so the tool is safe to call without side effects. The description adds behavioral context: it lists the exact return fields (digits, spread, tick value, etc.), notes that unknown symbols cause a tool error, and mentions that on replay sources synthetic=true is added. This goes beyond annotations without contradicting them.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise (three sentences) and front-loaded with the purpose. Each sentence adds relevant detail (return fields, naming, edge cases). Slightly verbose in listing fields could be trimmed, but it remains efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given that there is no output schema but an output schema exists (context says 'Has output schema: true'), the description thoroughly lists return fields and covers the key edge case of unknown symbols. With annotations providing read-only guarantee, and one simple parameter, the description is complete enough for an agent to use correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Even though schema coverage is 100% and the single parameter 'symbol' has a description, the description adds value by indicating that symbol names must match list_symbols exactly and that unknown symbols trigger an error. This aids correct invocation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Return the contract specification for one instrument,' which identifies the action (return) and the resource (contract specification for one instrument). It distinguishes itself from siblings like 'list_symbols' (which lists symbols, not specifications) and 'get_quote' (which gets quotes) by focusing on static contract details.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when needing instrument specifications (digits, spread, tick value, etc.) but does not explicitly state when to use this tool versus alternatives. It mentions that an unknown symbol returns a tool error, which is helpful context. No explicit exclusions or alternatives are given, but the context is clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

8 tool updatesv0.1.0Aug 19, 2026
- First observedget_account
- First observedget_bars
- First observedget_bars_range
- First observedget_quote
- First observedlist_orders
- First observedlist_positions
- First observedlist_symbols
- First observedsymbol_info

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.4/5.0

Scored 2026-09-09 17:50 across 8 tools

Disambiguation5/5

Each tool targets a distinct concern: symbol discovery, current quote, recent bars, ranged bars, contract specs, account summary, positions, and orders. The overlap between get_bars and get_bars_range is clearly delineated by recent-count vs. explicit time range, and descriptions reinforce the boundary.

Naming Consistency4/5

The set mostly follows a clear list_* for enumerations and get_* for single-item or snapshot retrievals. The one deviation is symbol_info, which lacks the get_ prefix, but the overall pattern remains predictable and readable.

Tool Count5/5

Eight tools is well-scoped for a read-only market data and account snapshot server. Each tool contributes a distinct capability without redundancy or bloat, and the count fits comfortably within the ideal range.

Completeness5/5

The surface covers symbol discovery, live quotes, historical bars, contract specifications, account summary, positions, and orders, with explicit read-only constraints explaining why trading mutations are absent. There are no obvious dead ends: list_symbols feeds the symbol-dependent tools, and get_bars/get_bars_range cover both recent and range-based history.

Maintenance

ActivityMaintained

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

openmm-mcp A
io.github.QBT-Labs
MCP server for OpenMM — exposes market data, account, trading, and strategy tools to AI agents
Finance
1513
Backtest360 A
com.backtest360
MCP server exposing the Backtest360 engine API as tools for AI agents.
Finance Research & Data
202
Marketdata App A
io.github.pipeworx-io
Market Data App MCP — wraps the Market Data App API (marketdata.app)
Finance Cryptocurrency
401
MTContext A
io.github.mtcontext
Connect any MCP client to MetaTrader 4/5 to read prices, manage positions, and place trades.
Finance Research & Data
1

Related MCP Servers

Meta-Trader-MCP
Finance AI & Machine Learning
shubhvisputek
A
license
Not graded
quality
A
maintenance
Exposes a unified AI interface to MetaTrader 5 over the Model Context Protocol, enabling live quotes, historical data, technical indicators, order execution, position management, and headless backtests.
Updated 4 months ago (2026-06-12 18:42 UTC)
MIT
ibkr-mcp
Finance
mark-liu
A
license
A
quality
C
maintenance
Read-only MCP server for Interactive Brokers that exposes market data, positions, and account info as MCP tools.
Updated 6 months ago (2026-04-17 23:11 UTC)
8
MIT
mt5-mcp
Finance Developer Tools
alikhande70
A
license
Not graded
quality
C
maintenance
A local-first MCP server that bridges AI coding agents with MetaTrader 5 for inspection, market data, MQL5 development, compiling, Strategy Tester review, workspace sync, logs, audit trails, demo trading, and carefully gated live trading.
Updated 3 months ago (2026-07-06 15:38 UTC)
MIT
tradingprogpt
Finance AI & Machine Learning
xentristech
F
license
Not graded
quality
C
maintenance
Read-only MCP server exposing MetaTrader 5 account and market data alongside Twelve Data quotes and technical indicators, with an LLM analysis layer.
Updated 3 months ago (2026-07-09 11:03 UTC)
-