Colonix en tu asistente de IA (MCP)
Si trabajas con un asistente de IA, puedes darle acceso a Colonix para que consulte códigos postales, colonias y claves del SAT mientras le pides cosas: revisar una dirección, armar el domicilio de una Carta Porte o ayudarte a programar la integración con respuestas reales. Se hace con un servidor MCP que corre en tu computadora, usa tu llave y solo lee.
MCP (Model Context Protocol) es el estándar con el que los asistentes usan herramientas externas.
El servidor de Colonix es el paquete de npm @silgaru/colonix-mcp: cada herramienta es un endpoint
de la API, con los mismos parámetros y los mismos planes. Además, el asistente tiene a la mano las
guías de esta documentación y el significado de cada campo de las respuestas, para explicarte bien
lo que recibe.
Qué le puedes pedir
Section titled “Qué le puedes pedir”- “¿Qué colonias tiene el código postal 06700?”
- “¿La colonia Guerrero es del 06300? Dame las claves para el complemento Carta Porte.”
- “Busca la colonia ‘Roma Nrte’ aunque esté mal escrita.”
- “¿Qué decía el SAT del código postal 22000 el 1 de marzo de 2026?”
- “¿Qué código postal corresponde a 19.4194, -99.1617?”
Lo que necesitas
Section titled “Lo que necesitas”- Node.js 22 o más reciente (nodejs.org).
- Tu llave de Colonix (cómo crearla).
Instalarlo
Section titled “Instalarlo”-
Abre Configuración → Desarrollador → Editar configuración.
-
Agrega el servidor a
claude_desktop_config.jsoncon tu llave:{"mcpServers": {"colonix": {"command": "npx","args": ["-y", "@silgaru/colonix-mcp"],"env": { "COLONIX_API_KEY": "tu-llave" }}}}En Windows, si no encuentra
npx, usa"command": "cmd"y"args": ["/c", "npx", "-y", "@silgaru/colonix-mcp"]. -
Reinicia Claude Desktop.
Con la llave en una variable, para que no quede escrita en el historial de la terminal:
# PowerShell 7$env:COLONIX_API_KEY = Read-Host -MaskInput "Llave de Colonix"claude mcp add colonix --scope user --env COLONIX_API_KEY=$env:COLONIX_API_KEY -- npx -y @silgaru/colonix-mcp# Bashread -rs COLONIX_API_KEYclaude mcp add colonix --scope user --env COLONIX_API_KEY=$COLONIX_API_KEY -- npx -y @silgaru/colonix-mcpAgrega a ~/.cursor/mcp.json (para todos tus proyectos) el mismo bloque que en Claude Desktop:
{ "mcpServers": { "colonix": { "command": "npx", "args": ["-y", "@silgaru/colonix-mcp"], "env": { "COLONIX_API_KEY": "tu-llave" } } }}Cualquier asistente que ejecute servidores MCP locales funciona: el comando es
npx -y @silgaru/colonix-mcp y la llave va en la variable de entorno COLONIX_API_KEY.
Las herramientas
Section titled “Las herramientas”| Herramienta | Endpoint | Plan |
|---|---|---|
get_postal_code |
Un código postal | Todos (los bloques opcionales, desde Básico) |
validate_postal_code_settlement |
Validar código postal y colonia | Todos (sat y cfdi, desde Básico) |
search_settlements |
Buscar asentamientos | Todos |
autocomplete_settlements |
Autocompletar | Todos |
list_postal_codes |
Listar códigos postales | Todos |
list_states, list_municipalities, list_municipality_settlements, list_settlement_types |
Estados, municipios, asentamientos de un municipio y tipos | Todos |
get_postal_code_history |
Historial de un código postal | Todos (sat, desde Básico) |
get_data_info |
Versión del dato | Todos |
get_sat_postal_code |
Datos del SAT de un código postal | Desde Básico |
reverse_geocode |
Código postal de un punto | Desde Básico |
find_nearby_postal_codes |
Códigos postales cercanos | Desde Básico |
batch_get_postal_codes |
Lote | Negocio y Enterprise |
list_changes |
Cambios | Negocio y Enterprise |
list_sat_discrepancies |
Diferencias SAT ↔ SEPOMEX | Negocio y Enterprise |
get_colonix_guide |
Ninguno: las guías de esta documentación y los campos de cada respuesta vienen en el paquete | Todos, sin gastar consultas |
Los códigos postales de demostración (06700, 44100, 64000, 22000 y 77500) muestran los datos del
SAT, la ubicación y la zona metropolitana en todos los planes. Si tu plan no incluye algo, el
asistente recibe el error plan-not-allowed y te lo dice.
Consumo
Section titled “Consumo”Cada vez que el asistente usa una herramienta es una consulta de tu plan,
igual que una llamada a la API (el lote cuenta una por código postal); get_colonix_guide no cuenta,
porque no llama a la API. El asistente decide cuántas hace: si le pides algo grande, puede hacer varias. El servidor le indica no recorrer páginas para
copiar el catálogo.
Las respuestas con error no cuentan. Por eso, si el asistente manda un código postal sin su cero
(6700) o el nombre de un estado donde va su clave, el servidor deja que conteste la API, que dice
cómo corregirlo (“Did you mean 06700?”), y le indica qué herramienta da la clave. En el lote no: ahí
cada código cuenta aunque esté mal escrito, así que el servidor lo revisa antes de consultar.
Seguridad
Section titled “Seguridad”- Solo lectura: ninguna herramienta cambia nada en tu cuenta.
- Tu llave solo viaja a
colonix.silgaru.mxpor HTTPS; el servidor no la escribe en ningún registro y no sigue redirecciones. - Sin dependencias: el paquete es solo su propio código, con licencia MIT, y no guarda nada en tu computadora.
© 2026 Silgaru