Skip to main content
Glama
mcp-direcciones-ar

mcp-direcciones-ar

mcp-direcciones-ar

MCP server para direcciones argentinas. Le da a Claude Code, OpenCode, Cursor o cualquier cliente MCP dos herramientas: buscar una dirección por texto y obtener la dirección más cercana a un punto. Envuelve el mismo contrato que el paquete Dart direcciones_ar sobre Nominatim (OpenStreetMap): sin API key, con caché y con el límite de una request por segundo que pide el servicio público.

Sin dependencias. Un solo node server.js.

{ "direccion": "Avenida Rivadavia 5000, Caballito", "barrio": "Caballito", "latitud": -34.6183831, "longitud": -58.4362001 }

Handshake y llamada real por stdio

Salida real del servidor MCP por stdio: initialize, tools/list y tools/call a buscar_direccion("rivadavia 5000 caballito").

Herramientas

Herramienta

Para qué

Devuelve

buscar_direccion

Autocompletar un campo de dirección ("rivadavia 5000 caballito")

Hasta 10 direcciones con calle, altura, barrio, localidad, CP y coordenadas

geocodificar_inverso

Saber qué hay en un punto del mapa

La dirección más cercana, o null si el punto no tiene una

Una lista vacía significa "no hay coincidencias"; un fallo del servicio es un error aparte. Esa distinción es la que permite decir "esa dirección no existe" en vez de "revisá tu conexión".

Related MCP server: chuk-mcp-geocoder

Instalar en un cliente MCP

Claude Code (~/.claude.json o .mcp.json del proyecto):

{
  "mcpServers": {
    "direcciones-ar": {
      "command": "node",
      "args": ["C:/ruta/a/mcp-direcciones-ar/server.js"]
    }
  }
}

OpenCode (opencode.json):

{
  "mcp": {
    "direcciones-ar": {
      "type": "local",
      "command": ["node", "C:/ruta/a/mcp-direcciones-ar/server.js"]
    }
  }
}

También se puede instalar como global y usar el binario:

npm install -g .
# y después "command": "mcp-direcciones-ar"

Variables de entorno:

Variable

Para qué

Default

NOMINATIM_URL

Apuntar a una instancia propia de Nominatim

https://nominatim.openstreetmap.org

Skill para agentes

El server solo no alcanza: un agente necesita saber cuándo conviene usarlo. Eso es un skill — un SKILL.md con las instrucciones — y está en skill/SKILL.md. Le dice al agente que lo use para autocompletar o validar una dirección argentina, qué hacer con una lista vacía, y cuándo no usarlo (otros países, geocodificación masiva).

Instalarlo en Claude Code, Cursor u otro agente que lea ~/.claude/skills/:

mkdir -p ~/.claude/skills/direcciones-ar
cp skill/SKILL.md ~/.claude/skills/direcciones-ar/SKILL.md

En OpenCode va en ~/.config/opencode/skills/direcciones-ar/SKILL.md. El skill no conecta el MCP: primero tiene que estar configurado como en la sección anterior, si no el agente no va a encontrar las herramientas.

Probar sin cliente

El servidor habla JSON-RPC 2.0 por stdin/stdout, un mensaje por línea. Se puede probar a mano:

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05"}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
  '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"buscar_direccion","arguments":{"consulta":"rivadavia 5000 caballito","limite":2}}}' \
  | node server.js

En Windows, con PowerShell:

@(
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05"}}',
  '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"buscar_direccion","arguments":{"consulta":"rivadavia 5000 caballito"}}}'
) | node server.js

Cómo está armado

server.js     protocolo MCP (initialize, tools/list, tools/call) sobre stdio
nominatim.js  cliente de Nominatim: caché LRU, cola de 1 req/s, parseo de la dirección
skill/        SKILL.md: cuándo y cómo usar las herramientas
test/         26 tests con fetch inyectado (no tocan la red)

Decisiones que importan:

  • El barrio va antes que la localidad en direccionCorta. En CABA la localidad es "Ciudad Autónoma de Buenos Aires" para las 15 comunas, así que mostrarla no distingue nada; el barrio sí.

  • Nada de logs por stdout: stdout es el canal del protocolo y un console.log lo rompe. Los diagnósticos van a stderr.

  • La cola serializa las llamadas: dos herramientas pidiendo direcciones a la vez no pueden comerse el rate limit del servicio público.

  • Las coordenadas se validan antes de salir a la red: un -120 de latitud es un error de quien llama, no una request al servidor.

Tests

npm test          # node --test, 26 tests

Los tests usan un fetch inyectado: verifican los parámetros que se mandan, la caché, el espaciamiento entre llamadas, los errores (500, JSON inválido, coordenadas fuera de rango) y el protocolo (initialize, tools/list, notificaciones sin respuesta, método desconocido). Ninguno sale a la red.

Además hay 8 tests del skill: que el frontmatter tenga nombre, descripción y licencia; que sólo nombre herramientas que existen en server.js; y que los parámetros documentados sean exactamente los del inputSchema. Si alguien renombra una herramienta o agrega un parámetro y se olvida del skill, el CI falla.

Límites

  • Es el servicio público de Nominatim: una request por segundo y uso moderado. Si vas a producción, levantá una instancia propia y apuntá NOMINATIM_URL.

  • Nominatim busca texto libre: una altura que no existe en OSM devuelve lista vacía. Ver el README de direcciones_ar para el detalle.

  • Sólo Argentina (countrycodes=ar) por defecto.

Publicar en npm y en el registro de MCP

Todavía no está publicado: se instala desde el repo. Cuando toque publicarlo, son dos pasos y ya está todo preparado:

  1. npm (el paquete incluye server.js, nominatim.js, skill/SKILL.md y server.json):

    npm login
    npm publish --access public

    package.json ya declara "mcpName": "io.github.lucabaello1998/mcp-direcciones-ar", que es lo que el registro oficial verifica contra el paquete publicado.

  2. Registro oficial de MCP (server.json, schema 2025-12-11). Requiere que el paquete exista en npm (el registro sólo guarda metadatos y no acepta repos de GitHub):

    # binario de github.com/modelcontextprotocol/registry/releases
    mcp-publisher validate
    mcp-publisher login github     # namespace io.github.lucabaello1998/*
    mcp-publisher publish
  3. Verificar y, recién ahí, cambiar el install del README a cero fricción:

    { "mcpServers": { "direcciones-ar": { "command": "npx", "args": ["-y", "mcp-direcciones-ar"] } } }
    curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=mcp-direcciones-ar"

Licencia

MIT. Ver LICENSE.

Available Tools

2 tools
buscar_direccionA

Busca direcciones argentinas por texto libre y devuelve calle, altura, barrio, localidad y coordenadas. Sirve para autocompletar un campo de dirección. Una lista vacía significa que no hay coincidencias.

Inputs: consulta (required), limite.

geocodificar_inversoA

Devuelve la dirección argentina más cercana a un punto (latitud, longitud). Si el punto no tiene una dirección asociada, devuelve null.

Inputs: latitud (required), longitud (required).

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 2 tools

    Disambiguation5/5

    The two tools cover opposite directions of geocoding: buscar_direccion maps free text to an address/coordinates, while geocodificar_inverso maps lat/lon back to an address. Their inputs and outputs are clearly distinct, so there is no realistic risk of misselection.

    Naming Consistency4/5

    Both names use Spanish snake_case with a leading verb (buscar_direccion, geocodificar_inverso), which reads as a consistent verb-first pattern. The second pairs its verb with an adjective rather than a noun, a minor deviation, but the convention is still predictable.

    Tool Count4/5

    Two tools is thin in absolute terms, but geocoding canonically has exactly two operations (forward and reverse), so each tool earns its place. The surface is well-scoped for the stated purpose.

    Completeness4/5

    Forward search (with autocomplete semantics) and reverse geocoding together cover the core lifecycle of an address/geocoding service, including empty-list and null edge cases. Minor gaps exist, such as address validation or normalization, but agents can work around them.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      F
      maintenance
      An MCP server providing geocoding and place discovery services via Nominatim and OpenStreetMap. It enables users to perform forward and reverse geocoding, extract bounding boxes, and find nearby places or administrative hierarchies.
      10
      Apache 2.0
    • A
      license
      A
      quality
      D
      maintenance
      Provides forward/reverse geocoding, bounding box extraction, nearby places discovery, batch geocoding, route waypoints, and administrative boundary lookup using OpenStreetMap data.
      10
      Apache 2.0