> Índice completo de la documentación: https://trackerintl.com/devs/llms.txt
> Esta página en HTML: https://trackerintl.com/devs/mcp
> Estado: Parcial, revisada el 2026-10-05. Probado únicamente contra un servidor simulado con datos ficticios (26 pruebas automáticas). No se ha usado contra una cuenta real de producción y el paquete todavía no se distribuye públicamente.

# 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](https://modelcontextprotocol.io) **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.

> **Estado y disponibilidad.**
>
> Hoy es un paquete en borrador y **no existe un servidor MCP público alojado por Tracker International**. Está pensado para distribuirse como un paquete que ejecutas tú, con tu propia cuenta y tu propio hash, en tu equipo o en tu infraestructura. La distribución del paquete y un alojamiento oficial están en evaluación. Si quieres probarlo, [escríbenos](/contacto).

## Requisitos

- Node.js 22 o superior.
- Un `user_api_hash` de tu cuenta. El servidor nunca pide ni procesa contraseñas. Mira [Autenticación](/devs/autenticacion).
- 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:

```bash
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:

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

```bash
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.

| 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](/devs/limites).

## 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.