norway-location-transport-mcp

Un servidor MCP que ofrece a los agentes de IA acceso estructurado a datos noruegos de transporte público y geodatos, a través de las API gratuitas de Entur y Kartverket / Geonorge.

Las dos fuentes se complementan: la planificación de viajes necesita geocodificación, la elevación necesita resolución de direcciones y las consultas administrativas vinculan coordenadas con lugares. Un solo servidor responde preguntas prácticas locales — "¿cómo llego de aquí a Bergen?", "¿cuál es la elevación a lo largo de esta ruta de senderismo?", "¿en qué municipio está esta dirección?", "¿hay patinetes eléctricos cerca?".

Ambas fuentes de datos son gratuitas, sin niveles de pago ni claves de API. Entur solo requiere una cabecera ET-Client-Name de autoidentificación (ver más abajo); Kartverket no requiere nada.

Herramientas

Ubicación y geodatos (Kartverket)

• search_address(query?, street?, number?, postal_code?, municipality_number?, max_results) — busca direcciones oficiales por texto libre o campos; admite el comodín *. Devuelve coordenadas y números catastrales.

• find_addresses_near(latitude, longitude, radius_m, max_results) — todas las direcciones dentro de un radio desde un punto, con distancias.

• validate_address(address) — valida y normaliza una dirección de texto libre (difusa). Devuelve valid, la coincidencia normalizada y alternativas.

• search_place_names(query, max_results) — busca nombres de lugares oficiales; devuelve el tipo de elemento (Fjell, Innsjø, …), municipio, condado y coordenadas. Admite *.

• find_place_names_near(latitude, longitude, radius_m, max_results) — los elementos nombrados más cercanos a un punto, con distancias.

• get_elevation(latitude, longitude) — elevación del terreno según el modelo nacional de elevación (DTM).

• get_elevation_profile(path, samples) — elevación muestreada a lo largo de una ruta; devuelve el perfil más la distancia total, el ascenso y el descenso.

• transform_coordinates(x, y, from_epsg, to_epsg) — convierte entre sistemas de referencia (p. ej. WGS84 4326 → UTM33 25833).

• lookup_admin_unit(latitude?, longitude?, address?) — en qué municipio y condado cae una coordenada o dirección, con códigos oficiales.

• lookup_property(address?, latitude?, longitude?, max_results) — identificadores catastrales (matrikkel) (kommune / gnr / bnr / fnr) a través del registro abierto de direcciones.

Transporte público (Entur)

• resolve_stop_place(query, max_results) — resuelve un lugar o dirección a los IDs de Stop Place de Entur.

• find_stops_near(latitude, longitude, radius_m, max_results) — geocodificación inversa de una coordenada a las paradas más cercanas.

• plan_trip(from_place?/from_latitude/from_longitude, to_place?/to_latitude/to_longitude, date_time?, arrive_by?, transport_modes?, walk_speed?, num_trip_patterns) — planifica un viaje de punto a punto; filtra por modo y velocidad de caminata. Devuelve patrones de viaje con tramos, modos, duraciones y tiempos en tiempo real.

• get_departures(stop_place_id, count) — próximas salidas desde una parada, con retrasos en tiempo real, cancelaciones y andén.

• get_realtime_status(stop_place_id? | line_id?) — estado en tiempo real: para una parada, recuentos de a tiempo/retrasado/cancelado; para una línea, vehículos activos y retrasos.

• get_stop_accessibility(stop_place_id) — accesibilidad para sillas de ruedas por andén y un resumen. (Ver la nota de accesibilidad más abajo.)

• list_quays(stop_place_id) — todos los andenes (plataformas) de una parada, con códigos y coordenadas.

• get_fare_zones(stop_place_id) — la(s) zona(s) tarifaria(s) a la que pertenece una parada.

• find_shared_vehicles(latitude, longitude, range_m, form_factors?, count) — vehículos compartidos de libre flotación (bicicletas, patinetes eléctricos, coches, ciclomotores) de todos los operadores.

• find_docking_stations(latitude, longitude, range_m, count) — estaciones de anclaje con recuentos de vehículos disponibles y huecos libres.

• get_vehicle_positions(codespace_id?, line_id?, max_results) — posiciones de vehículos en vivo con rumbo, velocidad y retraso.

Las definiciones de las herramientas viven en src/kartverket.ts y src/entur.ts, se combinan en src/tools.ts y son compartidas por los puntos de entrada stdio y HTTP.

Configuración

npm install
npm run build
npm test

npm test inicia el servidor a través de stdio y llama a cada herramienta contra las API en vivo.

Ejecutarlo

A través de stdio (para la mayoría de clientes MCP):

node dist/index.js

A través de Streamable HTTP (para clientes basados en HTTP):

node dist/http.js
# listens on http://localhost:3000/mcp  (override with PORT)

El requisito del nombre de cliente de Entur

Los términos de Entur exigen que cada solicitud lleve una cabecera ET-Client-Name identificativa, con el formato empresa-aplicación. Este servidor envía una en cada solicitud a Entur. Establece tu propio valor con la variable de entorno ET_CLIENT_NAME:

ET_CLIENT_NAME="acme-travelbot" node dist/index.js

Si no se establece, se usa un valor predeterminado del paquete. Kartverket no necesita cabecera ni clave.

Uso con Claude Code

claude mcp add norway -- node C:\Users\trond\norway-location-transport-mcp\dist\index.js

Luego pregunta, por ejemplo: "Planifica un viaje de Oslo S a Bergen y dime la elevación de Galdhøpiggen."

Versión remota (Cloudflare Workers)

worker/ contiene un despliegue remoto: las mismas 21 herramientas servidas a través de MCP Streamable HTTP, de modo que el servidor puede añadirse como conector de claude.ai. Comparte las definiciones de herramientas con el servidor local (src/tools.ts toma z como parámetro, por lo que funciona tanto con el SDK MCP local v1 / zod 3 como con el SDK v2 / zod 4 del worker).

cd worker
npm install
npm run dev     # local test at http://127.0.0.1:8787/mcp
node test-http.mjs

Despliégalo (necesita una cuenta de Cloudflare y wrangler login):

cd worker
npm run deploy

Establece tu nombre de cliente de Entur como variable del worker:

cd worker
npx wrangler secret put ET_CLIENT_NAME

Tras el despliegue, añade la entrada remotes con tu URL de workers.dev a server.json.

Ejemplos de llamadas

Obtén las próximas salidas desde Oslo S:

{ "name": "get_departures", "arguments": { "stop_place_id": "NSR:StopPlace:59872", "count": 5 } }

Planifica un viaje solo en autobús/tranvía con una velocidad de caminata fija:

{ "name": "plan_trip", "arguments": {
  "from_place": "NSR:StopPlace:59872",
  "to_latitude": 59.95, "to_longitude": 10.78,
  "transport_modes": ["bus", "tram"], "walk_speed": 1.4
} }

Perfil de elevación a lo largo de una ruta corta:

{ "name": "get_elevation_profile", "arguments": {
  "path": [{ "latitude": 61.636, "longitude": 8.312 }, { "latitude": 61.64, "longitude": 8.32 }],
  "samples": 20
} }

Convierte una coordenada WGS84 a UTM33:

{ "name": "transform_coordinates", "arguments": { "x": 10.7461, "y": 59.9127, "from_epsg": 4326, "to_epsg": 25833 } }

Notas y límites

• Coordenadas: son latitud/longitud WGS84 en todas partes. Las API de Kartverket se consultan con EPSG 4326 para que los números coincidan; EUREF89 (4258) difiere en menos de un metro en Noruega.

• Accesibilidad: el JourneyPlanner gratuito de Entur expone la accesibilidad para sillas de ruedas por andén. El detalle más profundo del equipamiento (ascensores, guías táctiles) solo existe en la API autenticada Stop Register de Entur y no está disponible aquí; la herramienta lo indica.

• Límite de velocidad: la limitación de velocidad de cualquiera de las fuentes se muestra como un error claro que pide al agente que reintente.

• Atribución: los datos de Kartverket / Geonorge y Entur están bajo NLOD. Da crédito a las fuentes cuando muestres los datos.

Cómo funciona

• src/index.ts habla MCP a través de stdio (JSON-RPC en stdin/stdout). src/http.ts habla MCP a través de Streamable HTTP con gestión de sesiones. Ambos construyen el mismo servidor mediante src/server.ts.

• Cada herramienta declara un esquema de entrada Zod con descripciones que el LLM lee directamente — no se necesitan documentos externos para llamar a una herramienta.

• Los resultados son texto JSON recortado a lo que un agente necesita, no las cargas útiles originales de los proveedores.

• Nunca escribas en stdout con console.log; corrompe el protocolo stdio. Registra en stderr.

Licencia

MIT © Trond Bjørøy. Datos © Kartverket y Entur, bajo NLOD.