de en es ja ko ru zh

QUOTEZ

Name: QUOTEZ
Author: PNX89

by PNX89

Overview Schema Source Related Servers Discussions Admin

Python

Local

QUOTEZ

Datos de mercado para agentes. Solo lectura por construcción, no por configuración.

Python License: MIT

Un servidor MCP que expone datos de mercado de MetaTrader 5 como herramientas tipadas y de solo lectura que un agente LLM puede llamar. Python 3.11 o más reciente, una dependencia en tiempo de ejecución, transporte stdio. La insignia se detiene en 3.13 porque ahí es donde se detienen los clasificadores; CI también ejecuta una rama 3.14, marcada como advisory, y 3.14 se une a la insignia una vez que haya estado verde el tiempo suficiente para ser una promesa en lugar de una esperanza.

Un agente solo es tan bueno como las herramientas que le entregas, y los datos de mercado es donde una herramienta descuidada causa daños reales. El modelo repite como hecho cualquier cosa que una herramienta devuelva, por lo que un payload sin unidades, sin zona horaria y sin procedencia se convierte en una frase segura sobre un precio sobre el que alguien podría actuar. QUOTEZ responde con esquemas de salida generados en lugar de bloques de texto, UTC en todas partes, un flag synthetic en cada payload y ninguna ruta de escritura en el código.

Esta es una herramienta construida para que no pueda causar daño, lo cual es una pregunta más pequeña y verificable que si se puede confiar en un agente en su conjunto con herramientas. Esa pregunta más grande es de QUELLZ.

Alcance y límites

Solo lectura: no order_send, no order_check, no symbol_select, sin escrituras de ningún tipo.
Los datos en vivo de MetaTrader necesitan Windows y un terminal en ejecución; las ruedas son solo win_amd64.
La fuente predeterminada reproduce datos generados y etiqueta cada payload como synthetic: true.
Las horas son UTC y cada barra está etiquetada por su apertura, el borde izquierdo de su intervalo.

Related MCP server: ibkr-mcp

Ejemplo de sesión de agente

Salida real, no un pegado. Regenera con uv run python examples/agent_session.py; tests/test_readme.py verifica que este bloque sea byte por byte contra la salida estándar de ese comando. Los precios de reproducción son generados, no registrados de ningún mercado.

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.

Inicio rápido

Un comando, nada que configurar, sin instalación de MetaTrader en ningún lado:

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

QUOTEZ no está publicado en PyPI, por lo que la forma git es la instalación; añade @main, una etiqueta o un commit para fijar una referencia, según la documentación de dependencias de uv. Luego parece colgarse, porque stdout es el cable JSON-RPC y un host lo maneja. Para verlo funcionar sin un host, clona el repositorio y ejecuta la sesión de ejemplo, que maneja el mismo servidor desde un cliente en proceso:

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

En Windows, contra un terminal ya en ejecución e iniciado sesión:

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

El script de consola es el único punto de entrada que acepta flags, y los flags ganan sobre el entorno. mcp run src/quotez/server.py también sirve este servidor a través del global mcp a nivel de módulo, pero no reenvía nada, por lo que esa ruta lee las variables en su lugar.

Flag	Variable de entorno	Por defecto	Significado
`--source`	`QUOTEZ_SOURCE`	`replay`	`replay` lee los archivos generados incluidos, `mt5` lee un terminal en vivo
`--symbols`	`QUOTEZ_SYMBOLS`	empty	Lista blanca separada por comas, sin distinción de mayúsculas y minúsculas. Vacío expone todo lo que tiene la fuente
`--max-bars`	`QUOTEZ_MAX_BARS`	`1000`	Máximo de barras que una llamada puede devolver, de 1 a 5000
`--log-level`	`QUOTEZ_LOG_LEVEL`	`INFO`	Umbral de registro. Los registros siempre van a stderr, porque stdout es el cable

Conéctalo a un host

Los hosts no se ponen de acuerdo en la clave de configuración, y confundir mcpServers con servers es la razón habitual por la que un servidor nunca aparece.

Host	Archivo	Clave
Claude Desktop	`~/Library/Application Support/Claude/claude_desktop_config.json` en macOS, `%APPDATA%\Claude\claude_desktop_config.json` en Windows	`mcpServers`
Cursor	`.cursor/mcp.json`	`mcpServers`
VS Code	`.vscode/mcp.json`	`servers`, y añade `"type": "stdio"` junto a `command`
Claude Code	sin archivo, usa la CLI	`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 debe ser la ruta absoluta de which uv. Un host inicia el servidor con un PATH casi vacío, por lo que un uv desnudo es la razón más común por la que un servidor falla silenciosamente al conectarse.

Herramientas

Ocho herramientas, registradas en este orden, que es el orden que devuelve tools/list; los clientes almacenan en caché esa lista, por lo que el orden está fijado a propósito. Un recurso, symbols://list, sirve el mismo universo de instrumentos que application/json.

Herramienta	Argumentos	Devuelve	Acceso	Fuente de reproducción	Fuente MetaTrader
`list_symbols`	`group` opcional, sintaxis de grupo de MetaTrader	`SymbolList`	lectura	4 instrumentos generados	`symbols_get(group=...)`
`get_quote`	`symbol`	`Quote`	lectura	derivado de la última barra almacenada	`symbol_info_tick`
`get_bars`	`symbol`, `timeframe`, `count` (1 a 5000, limitado por `--max-bars`)	`BarSeries`	lectura	M1 resumido localmente	`copy_rates_from_pos`
`get_bars_range`	`symbol`, `timeframe`, `start`, `end`	`BarSeries`	lectura	M1 resumido localmente	`copy_rates_range`
`symbol_info`	`symbol`	`SymbolSpec`	lectura	desde `symbols.json`	`symbol_info`
`get_account`	ninguno	`Account`	lectura	cifras de marcador de posición, `synthetic: true`	`account_info`, login enmascarado
`list_positions`	ninguno	`PositionList`	lectura	siempre vacío	`positions_get`
`list_orders`	ninguno	`OrderList`	lectura	siempre vacío	`orders_get`

list_symbols toma la propia sintaxis de filtro de grupo de MetaTrader en lugar de inventar una: comodines * al inicio y final de un patrón, condiciones separadas por comas, y ! para negar una. Las inclusiones deben ir antes que las exclusiones, por lo que "*, !*USD*" es todo excepto los instrumentos USD mientras que "!*USD*, *" coincide con todo. Mt5Source pasa la cadena a symbols_get; la fuente de reproducción ejecuta la misma sintaxis a través de quotez.groups, por lo que ambas responden a un filtro de manera idéntica.

Cada herramienta devuelve un modelo Pydantic, por lo que el SDK deriva un outputSchema de la anotación de retorno, llena structuredContent y valida el payload antes de que salga del servidor. Se usa un BaseModel sin envolver, por lo que get_bars devuelve un objeto con una clave bars en lugar de {"result": ...}.

Cómo funciona

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 es la costura contra la que está escrito todo el servidor. Nada por encima de él importa MetaTrader5, y Mt5Source resuelve la extensión dentro de un helper privado en el primer uso en lugar de en la importación del módulo, por lo que import quotez funciona donde no existe ninguna rueda. Eso es lo que hace que ReplaySource sea una implementación de primera clase en lugar de un mock: la capa de herramientas no puede distinguir entre los dos, por lo que todo el conjunto ejercita la ruta de código real sin un terminal instalado.

Los datos incluidos son cuatro instrumentos generados (SYNTH_FX_ALPHA, SYNTH_FX_BETA, SYNTH_IDX_GAMMA, SYNTH_MTL_DELTA), 3600 barras M1 cada uno, de 08:00 a 14:00 UTC en días laborables del 2026-06-01 al 2026-06-12, con nueve pausas de sesión, ocho nocturnas y una durante un fin de semana, porque una serie sin espacios es la serie que oculta un error de agregación. scripts/generate_replay_data.py produjo los archivos una vez a partir de un random.Random con semilla y la salida está confirmada. Los CSV se leen a través de importlib.resources, nunca Path(__file__).parent, lo que funciona en un checkout y se rompe bajo la instalación comprimida que realiza uvx.

Herramientas y recursos no son lo mismo

Una herramienta es lo que el MODELO decide llamar; un recurso es lo que la APLICACIÓN decide cargar. get_bars está impulsado por el modelo: elige un símbolo, un marco temporal y un recuento en medio del razonamiento. symbols://list está impulsado por la aplicación: un host fija el universo en el contexto una vez, antes de que el modelo haya decidido nada. Por eso no es una duplicación incidental de list_symbols, que es una búsqueda filtrada que el modelo ejecuta a propósito.

El siguiente recurso obvio, bars://{symbol}/{timeframe}, no se construyó deliberadamente: duplica get_bars para los mismos datos, y un URI con marcadores de posición es una plantilla de recurso, lo que deja resources/list por resources/templates/list y es mostrado deficientemente o no mostrado en absoluto por muchos hosts. Una prueba afirma que no hay plantillas de recursos registradas.

Agregación de marcos temporales

La fuente de reproducción almacena un marco temporal base, M1, y quotez.aggregate resume M5, M15, M30, H1, H4 y D1 a partir de él. Una copia almacenada, un resumen, comprobable por sí mismo, lo cual importa porque su modo de fallo es silencioso: una agregación incorrecta devuelve números plausibles para siempre y nunca lanza una excepción.

La fuente MetaTrader no resume nada. Un terminal ya contiene cada período, por lo que se le pide el marco temporal directamente; derivarlos nuevamente de M1 sería más lento y discreparía con los gráficos que el operador tiene abiertos. Por lo tanto, las dos fuentes responden a la misma llamada de manera ligeramente diferente en D1, H4 y spread, lo cual está en Limitaciones en lugar de dejarlo para que lo encuentres.

Los invariantes del resumen, cada uno de los cuales es un nombre de prueba:

M1 es el único marco temporal base. Todo lo más grueso se deriva.
Los buckets son de reloj de pared, calculados mediante división por suelo del segundo epoch, nunca agrupando cada N filas posicionalmente.
Los objetivos son múltiplos enteros de 60 segundos. Cualquier otra cosa lanza InvalidRequest.
OHLC es primero apertura, máximo alto, mínimo bajo, último cierre.
tick_volume se suma. spread no: es una propiedad puntual de una cotización, por lo que una barra agregada reporta null.
Las barras se etiquetan por su borde izquierdo, en UTC.
Un bucket final incompleto se descarta en lugar de emitirse como barra parcial. Un bucket se emite solo cuando la entrada contiene una barra en o después del final de ese bucket.
Una entrada vacía devuelve una lista vacía.

El invariante 2 se gana sus pruebas. El agrupamiento posicional coincide con el bucketing por reloj de pared en una serie sin huecos y discrepa en cuanto hay un hueco: agrupar sesiones de 360 barras de a cuatro pone el cierre del viernes y la apertura del lunes en una misma barra y la llama vela de cuatro horas. El invariante 7 es su par, porque el final de una sesión no es el mismo evento que el agotamiento de los datos.

Diseño de seguridad

La afirmación es estructural, no configurable. Este código base no contiene ninguna ruta de escritura. No hay order_send, ni order_check, ni symbol_select, ni mutación de MarketWatch ni escritura de archivos en ningún lugar de src/quotez/. Ninguna configuración puede activar una escritura, porque no hay nada que activar.

Dos pruebas lo mantienen en su lugar, y la segunda es la que realmente importa. La primera busca en el paquete esas tres llamadas de MetaTrader: barata, cubre todos los archivos y se satisface con un nombre ensamblado en tiempo de ejecución. La segunda recorre el AST de mt5source.py y afirma la propiedad positiva: que el conjunto de atributos que este paquete lee del módulo terminal es exactamente las llamadas de lectura que nombra su propio docstring más las siete constantes de marcos temporales, sin nada alcanzado a través de getattr y sin nada reasignado a una segunda variable. _mt5() devuelve todo el módulo MetaTrader5, por lo que la ausencia de tres nombres entre varios cientos de atributos prueba muy poco por sí sola. Se verifican cinco fragmentos deliberadamente rotos contra ese recorrido para que se sepa que el recorrido falla cuando debe.

Cada herramienta se declara ToolAnnotations(read_only_hint=True, open_world_hint=False). Esa declaración es una cortesía hacia los clientes y nada más: la especificación MCP indica a los clientes que traten las anotaciones de herramientas como no confiables a menos que provengan de un servidor confiable. read_only_hint=True describe la herramienta, no restringe al cliente, y la propiedad que un revisor puede verificar es la ausencia de las llamadas, no la presencia de la bandera. Mapeado a las Consideraciones de seguridad para herramientas de la propia especificación, incluyendo el requisito que este servidor no cumple:

Requisito de la especificación	QUOTEZ	Dónde
Validar todas las entradas de herramientas	Sí	JSON Schema derivado de las sugerencias de tipo, marcos temporales `Literal`, `Field(ge=1, le=5000)` en `count`, más comprobaciones en tiempo de ejecución en los manejadores
Implementar controles de acceso adecuados	Sí	la lista blanca de símbolos se aplica a cada herramienta y al recurso, no solo a los getters
Limitar la tasa de invocaciones de herramientas	No	no implementado, y listado en Limitaciones. Un servidor stdio es un proceso hijo de exactamente un anfitrión, por lo que el anfitrión posee el límite de tasa
Sanitizar las salidas de las herramientas	Sí	el inicio de sesión de la cuenta se enmascara a sus últimos cuatro dígitos, los nombres del bróker, servidor y titular de la cuenta nunca se devuelven, y `synthetic` es un campo obligatorio en cada carga útil

Un símbolo bloqueado se reporta como SymbolNotFound con el mensaje que obtendría un error tipográfico: "El símbolo 'X' no está disponible en este servidor." Un "no permitido" distinto convertiría la lista blanca en un oráculo de descubrimiento para instrumentos que un operador decidió no exponer.

Los errores toman uno de dos canales, elegidos según si un modelo más inteligente podría haber evitado el fallo. Un símbolo mal escrito podría serlo, por lo que SymbolNotFound e InvalidRequest son excepciones ordinarias, que se convierten en errores de herramienta que el modelo puede leer y reintentar. Un terminal que no está en ejecución no podría, por lo que SourceUnavailable se lanza como MCPError, un error de protocolo sin ningún resultado. Nada aquí devuelve una cadena de error: una cadena devuelta lleva is_error=False y se lee como una respuesta exitosa. Una prueba llama a cada herramienta con entrada incorrecta y afirma la bandera.

Decisiones de diseño

mcp>=2.0.0,<3 y MCPServer, no la versión v1 ni FastMCP. El SDK todavía ofrece mcp>=1.28,<2 para quienes no han migrado, pero un servidor de la era v1 se delata en tres segundos: from mcp.server.fastmcp import FastMCP. La guía de migración tiene los cambios de nombre. El Server de bajo nivel era la alternativa y ya no envuelve automáticamente los valores de retorno, por lo que significaba escribir a mano JSON Schema para ocho herramientas.

Retornos tipados con Pydantic, no bloques de texto. La mayoría de los servidores MCP públicos devuelven prosa y dejan que el modelo la analice. Aquí la anotación de retorno es el esquema de salida, por lo que tipado no cuesta nada y compra validación antes de que la carga útil salga del servidor.

Dos herramientas de barras, no una con argumentos opcionales. JSON Schema no puede expresar exclusividad mutua, por lo que un solo get_bars(count or start..end) empujaría "uno de estos pero no ambos" al modelo como prosa. Dos herramientas tienen dos esquemas completamente válidos, y la clase de error "ambos dados, ninguno dado" deja de existir.

Datos generados, no un feed real. Una decisión de licencia, no una preferencia. Las exportaciones de MetaTrader son el feed licenciado del bróker, y para los CFD de índices y acciones el subyacente tiene licencia de la bolsa. Las páginas de ayuda de Yahoo establecen la restricción en tantas palabras, no debe redistribuir información mostrada o proporcionada por Yahoo Finance, y sus términos de API para desarrolladores restringen por separado la venta o sublicencia de acceso. Las FAQ de HistData no otorgan ningún derecho de redistribución; solo dice que los datos vienen sin garantía, y el silencio no es una licencia. Comprometer cualquiera de ellos en un repositorio MIT relicenciaría datos que no tengo derecho a relicenciar.

La biblioteca estándar, no pandas ni numpy. A escala de CSV empaquetado, csv más datetime más dataclasses es suficiente y el árbol se mantiene auditable. Ese árbol merece ser nombrado honestamente, todo él: mcp 2.x es una dependencia directa que trae anyio, httpx2, jsonschema, mcp-types, opentelemetry-api, pydantic, pyjwt con su extra crypto, python-multipart, sse-starlette, starlette, typing-extensions, typing-inspection y uvicorn, más pywin32 en Windows. El extra crypto trae cryptography, cffi y pycparser detrás. Es una huella mayor que v1, y una prueba lee el uv.lock confirmado y falla si esta lista deja de coincidir, porque un párrafo que existe para nombrar el árbol no vale nada si nombra la mayor parte del árbol.

Sin herramienta run_backtest. Un backtest no tiene límite de cómputo, necesita mucho más que un MarketDataSource, y duplicaría QUACKZ, por lo que el par se leería como dos medios proyectos en lugar de dos enfocados. Por la misma razón, las salvaguardas aquí son locales al dominio: validación de entrada, consultas acotadas, un universo de instrumentos fijo, sin efectos secundarios. Las salvaguardas generales de agentes pertenecen a QUELLZ, no reinventadas cinco veces.

Limitaciones

Ningún ejecutor de integración continua ejercita la ruta en vivo de MetaTrader, en ningún lugar. No hay rueda para no Windows y ningún ejecutor tiene un terminal o una cuenta de bróker. El trabajo de Windows prueba que la extensión se importa y que Mt5Source reporta un terminal faltante limpiamente, y eso es todo. El mapeo de campos de Mt5Source es el código menos ejercitado aquí, cubierto por pruebas de módulos falsos.
MetaTrader5 es solo para Windows y no publica una distribución fuente, por lo que pip install quotez[mt5] es un no-op en macOS y Linux por diseño. Una prueba afirma que el marcador de entorno lo mantiene así.
initialize() lanza el terminal si no está ya en ejecución, y toda la operación está limitada por su argumento timeout, documentado con un valor predeterminado de 60000 milisegundos. La página no da una cifra para el lanzamiento en sí, así que trate 60 segundos como el techo de la llamada en lugar de un tiempo de inicio medido. QUOTEZ abre la conexión una vez en la vida del servidor en lugar de por llamada, por lo que cueste lo que cueste, aterriza al inicio en lugar de hacer que la primera llamada de herramienta parezca colgada.
Las dos fuentes no coinciden en dónde comienza un bucket D1 o H4. El roll up de reproducción aplica suelo en el segundo epoch, por lo que D1 abre a las 00:00 UTC y H4 a las 00, 04, 08, 12, 16 y 20 UTC. Un terminal MetaTrader alinea D1 y H4 con el día del servidor del bróker, que comúnmente es UTC+2 o UTC+3, por lo que el mismo get_bars(symbol, "D1") devuelve una vela con una hora de apertura diferente y OHLC diferente dependiendo de qué fuente esté configurada. Nada aquí remuestrea el M1 del terminal para ocultar eso, porque una barra que discrepa del propio gráfico del operador es peor que un desplazamiento documentado.
Por la misma razón, spread es nulo en cada barra de reproducción por encima de M1 y se establece en cada barra de MetaTrader. El roll up lo limpia a propósito; el terminal reporta su propio valor en cada marco temporal y QUOTEZ lo pasa sin descartar datos que la fuente le dio.
copy_rates_from_pos y copy_rates_range están silenciosamente limitados por la configuración "Máx. barras en gráfico" del terminal, por lo que una solicitud dentro del propio límite del servidor aún puede devolver menos y nada en la API de MetaTrader lo dice.
get_bars omite la barra que el terminal aún está construyendo, por lo que su barra más nueva siempre está cerrada. get_bars_range no lo hace, porque los límites son del llamante: un end dentro del intervalo actual devuelve la barra parcial de ese intervalo.
symbol_info() devuelve None para un símbolo desconocido en lugar de lanzar una excepción, al igual que symbols_get() en caso de error. Cada sitio de llamada aquí lo verifica, pero esa es la forma de la API que se está envolviendo.
MetaTrader almacena los tiempos de barras y ticks en UTC sin desplazamiento, mientras que un datetime ingenuo de Python se resuelve contra la zona local; la documentación de copy _rates _range lo dice. Cada marca de tiempo saliente se construye con tz=UTC y las entradas ingenuas se rechazan, pero esta es la trampa que desplaza silenciosamente una serie completa por una hora.
Sin limitación de tasa. Un servidor stdio es un proceso hijo de un anfitrión, y el anfitrión posee eso.
Los datos de reproducción son de escala de muestra y generados: 4 instrumentos, 3600 barras M1 cada uno, diez días de negociación. Demuestra las herramientas y ejercita la agregación, y no es ni un conjunto de datos de investigación ni un mercado.
La versión 0.1.0 es solo lectura y solo stdio, sin capacidad de prompts, sin transporte SSE o HTTP transmisible y sin OAuth.

Por qué construí esto

He estado escribiendo software de trading desde 2017, y cada proyecto comienza de la misma manera: encontrar una fuente de datos, escribir el adaptador, probarlo, tirarlo cuando el bróker cambia. QUOTEZ es el adaptador que quiero conservar. Es pequeño, tipado, solo lectura y probado contra dos fuentes para que la abstracción sea real. Si tienes un terminal MetaTrader y una cuenta demo, pip install quotez[mt5] y las herramientas aparecen en tu anfitrión MCP. Si no, la fuente de reproducción funciona de inmediato y muestra la misma interfaz. De cualquier manera, los datos son tuyos para consultar, no míos para servir.

Realizo investigaciones de walk forward sobre datos de índices y mantengo terminales MetaTrader para la parte de FX y metales, por lo que ambas mitades ya estaban en mi escritorio. Lo que me llevó a escribirlo fue ver a un agente repetir un número de una herramienta mal tipada como si fuera un hecho, sin unidad, sin zona horaria y sin indicar de dónde provenía. En datos de mercado, eso no es cosmético: una barra etiquetada por su cierre en lugar de su apertura, o una marca de tiempo desplazada silenciosamente a la hora local, da una respuesta que parece correcta pero está desfasada por una hora. Así que esto trata principalmente de decisiones sobre la procedencia y sobre lo que una herramienta puede afirmar, envueltas en un poco de código de agregación.

Desarrollo

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

251 pruebas, sin red, unos segundos, e idéntico en macOS, Linux y Windows. Ese recuento se afirma contra una colección real ejecutada, porque un número en un README es un número que nadie actualiza.

Licencia

MIT. Ver LICENSE.

Parte del conjunto de herramientas Q...Z, cinco herramientas para el fallo que no se anuncia a sí mismo:

QUACKZ, desinflando un backtest que solo se ve bien porque fue seleccionado entre doscientos.
QUOTEZ, esta: datos de mercado que un agente puede leer y no puede actuar sobre ellos.
QUELLZ, midiendo lo que cuesta la contención de inyección de indicaciones en utilidad y en tasa de ataque.
QUIDZ, rechazando el pago saliente que se habría duplicado.
QUESTZ, deteniendo un scraper antes de que escriba un CSV desde una página que cambió de forma.

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)
-