Servidor MCP

Servidor MCP de solo lectura para que un asistente de IA consulte tu cuenta de la plataforma GPS: herramientas, instalación, seguridad y límites.

El servidor MCP de Tracker International permite que un asistente de IA compatible con el Model Context Protocol consulte tu cuenta de la plataforma GPS: vehículos, posiciones, historial, eventos, geocercas y reportes. Es de solo lectura: no tiene herramientas que modifiquen datos, envíen comandos, generen reportes ni administren clientes.

Requisitos #

Node.js 22 o superior.
Un user_api_hash de tu cuenta. El servidor nunca pide ni procesa contraseñas. Mira Autenticación.
Recomendado: un usuario dedicado con permisos únicamente de "ver", porque el hash concede los mismos permisos que la contraseña.

Instalación #

Con el paquete en tu equipo:

cURL

cd mcp-server
npm install
npm test
npm run demo

npm test ejecuta 26 pruebas sin red, contra un servidor simulado. npm run demo hace una llamada por herramienta, por stdio y por HTTP, también contra el simulado.

Configuración #

Variables de entorno principales:

Configuración
Variable	Valor por defecto	Para qué sirve
`TRACKER_API_HASH`	(ninguno)	Credencial para el transporte stdio. En HTTP llega por cabecera.
`TRACKER_API_BASE_URL`	`https://plataforma.trackerintl.com`	Dominio base. Debe ser https (http solo en localhost).
`TRACKER_RATE_LIMIT_PER_MINUTE`	60	Peticiones por minuto y por credencial hacia la plataforma.
`TRACKER_MAX_RANGE_DAYS`	31	Rango máximo de fechas en historial, posiciones y eventos.
`TRACKER_MAX_OUTPUT_CHARS`	60000	Tope de la respuesta de cada herramienta.
`TRACKER_LANG`	(ninguno)	Idioma de los textos traducibles (`es`, `en`).

Conectarlo a un cliente #

Claude Desktop (stdio) #

En claude_desktop_config.json:

JSON

{
  "mcpServers": {
    "tracker-gps": {
      "command": "node",
      "args": ["/ruta/absoluta/mcp-server/src/stdio.js"],
      "env": {
        "TRACKER_API_HASH": "TU_API_HASH",
        "TRACKER_API_BASE_URL": "https://plataforma.trackerintl.com"
      }
    }
  }
}

Claude Code (stdio) #

cURL

claude mcp add tracker-gps --env TRACKER_API_HASH='TU_API_HASH' -- node /ruta/absoluta/mcp-server/src/stdio.js

Clientes HTTP #

El transporte HTTP escucha por defecto en 127.0.0.1:3333 (endpoint POST /mcp) y no tiene sesiones. La credencial va en cada petición, en la cabecera X-Tracker-Api-Hash (o Authorization: Bearer). El servidor no termina TLS: si lo expones fuera de tu equipo, ponlo detrás de un proxy HTTPS y restringe el acceso por red.

Herramientas #

Todas son de solo lectura (readOnlyHint). Por defecto devuelven proyecciones compactas; las que lo permiten aceptan raw: true para la respuesta cruda.

Herramientas del servidor MCP
Herramienta	Qué hace	Endpoint de la API
`get_account`	Datos de la cuenta	`GET /api/get_user_data`
`list_vehicles`	Listar vehículos	`GET /api/get_devices`
`get_latest_positions`	Últimas posiciones / cambios recientes	`GET /api/get_devices_latest`
`get_route_history`	Historial de recorrido por tramos	`GET /api/get_history`
`get_position_messages`	Posiciones GPS crudas (paginadas)	`GET /api/get_history_messages`
`list_events`	Eventos y alertas disparadas	`GET /api/get_events`
`list_alerts`	Reglas de alerta configuradas	`GET /api/get_alerts`
`get_alerts_summary`	Resumen de eventos por tipo	`GET /api/get_alerts_summary`
`list_geofences`	Geocercas	`GET /api/get_geofences`
`point_in_geofences`	Geocercas que contienen un punto	`GET /api/point_in_geofences`
`get_vehicle_geofences`	Geocercas donde está un vehículo ahora	`GET /api/devices_in_geofences`
`list_routes`	Rutas planificadas	`GET /api/get_routes`
`list_report_types`	Tipos de reporte disponibles	`GET /api/get_reports_types`
`list_saved_reports`	Reportes guardados	`GET /api/get_reports`
`list_drivers`	Conductores	`GET /api/get_user_drivers`
`list_sent_commands`	Comandos enviados a los equipos	`GET /api/sent_commands`

La lista sale del manifiesto del servidor en cada compilación de este portal, no se escribe a mano.

Seguridad #

Solo lectura por construcción: el cliente HTTP del servidor solo expone GET. Aun así, el hash que le des sigue pudiendo escribir si alguien lo usa fuera de este servidor; por eso conviene un usuario con permisos solo de "ver".
La credencial se lee del entorno (stdio) o de la cabecera de cada petición (HTTP), no se guarda en disco y viaja hacia la plataforma solo en la cabecera user-api-hash, nunca en la URL.
Registros: solo incluyen el nombre de la herramienta, el código y la duración, sin argumentos, cuerpos ni credenciales.
HTTP: rechaza Origin no autorizado, limita el tamaño del cuerpo y escucha solo en loopback por defecto.
Se rechazan las redirecciones, para no reenviar la cabecera a otro host.

Límites #

60 peticiones por minuto y por credencial desde el servidor (configurable), con una espera máxima de 10 segundos.
Rango máximo de 31 días en historial, posiciones y eventos.
limit de 200 como máximo; en posiciones crudas, solo 50, 100, 200, 300, 400, 500 o 1000.
Salida máxima de 60.000 caracteres por herramienta.
Los límites de la plataforma aparecen en Límites.

Qué no está verificado #

No se hizo ninguna petición autenticada a producción desde este servidor. Las formas de respuesta se midieron ejecutando el código de la plataforma en un entorno de pruebas con datos ficticios y se contrastaron con producción por diff. Tampoco se verificó la respuesta real del inicio de sesión ni de las consultas de geocercas por punto o por vehículo.