bilbao-avisos-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@bilbao-avisos-mcp genera un aviso por esta foto de una farola rota en Gran Vía"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
bilbao-avisos-mcp
Servidor MCP (y CLI de apoyo) para el sistema de avisos del Ayuntamiento de Bilbao (MeJora Bilbao / Bilbo Hobetuz). Permite a un agente listar categorías, buscar calles, consultar avisos y crear avisos con inteligencia artificial — incluso desde una foto.
La finalidad de este proyecto es hacer más fácil que los ciudadanos puedan reportar problemas al Ayuntamiento de Bilbao. Saca una foto de la incidencia (por ejemplo, basura tirada en la calle, una farola que no funciona…) pásasela al agente pidiéndole que genere un aviso para que de forma autónoma describa el problema, seleccione la categoría más adecuada, añada la ubicación (la foto tiene que estar geolocalizada) y lance el aviso al Ayuntamiento.
Inicio rápido
Bilbao no usa cuenta de ciudadano: la app se autentica con una cuenta de servicio (Keycloak, grant password) y cada aviso lleva los datos del comunicante.
Credenciales de servicio (las que usa la propia app; van en el entorno, no en el código):
export BILBAO_AVISOS_USERNAME=999400 export BILBAO_AVISOS_PASSWORD=s7rvq45XJ2Si el Ayuntamiento las rota, relee tu copia del APK de "Mejora Bilbao" (
grep -o 'token_credentials:{[^}]*}' assets/public/main.*.js) o pide credenciales propias.Añade el servidor a tu cliente MCP (ejemplos) o configúralo a mano:
{
"mcpServers": {
"bilbao-avisos": {
"command": "npx",
"args": ["-y", "bilbao-avisos-mcp"],
"env": { "BILBAO_AVISOS_USERNAME": "999400", "BILBAO_AVISOS_PASSWORD": "s7rvq45XJ2" }
}
}
}Verifica:
check_authdebe devolvercomprobarVersionconestadoVersion.Pregunta al humano UNA vez su idioma (
es/eu), nombre, primer apellido y teléfono o email; guárdalo con la toolset_identity. Se reutiliza en todos los avisos.Flujo del agente:
create_aviso_from_photo(foto → categoría → calle → preview) → enseña el preview al humano →confirm: true+human_confirmed: true+preview_tokensolo con su "sí" →attach_photo.
Todo corre en tu máquina; los avisos se crean con tu cuenta de servicio y los datos del comunicante guardados.
Related MCP server: valencia-avisos-mcp
Fotos demasiado grandes para el modelo
Algunos modelos rechazan fotos muy grandes (image decode limit exceeded). El servidor
reduce en TypeScript (sin dependencias) conservando el GPS, así que el modelo nunca
necesita procesar la original:
Remoto (HTTP): sube la foto con curl y usa el
file_id(los bytes no pasan por el modelo). Requiere el secreto del servidor:curl -X PUT --data-binary @foto.jpg \ -H "Authorization: Bearer ***" \ 'http://127.0.0.1:3000/upload?filename=foto.jpg' # → {"file_id":"…","bytes":…}El preview devuelve
preview_image_base64(copia reducida) para visión y adjunta siempre la original.Local (stdio/CLI): pasa
image_path; el servidor lee y reduce sin que el modelo abra el fichero. O reduce tú connode dist/cli.js prep-photo foto.jpg [foto-ligera.jpg].
¿Eres un agente IA? Lee esto primero
La skill (skill/SKILL.md) no se autoinstala: cópiala al directorio de tu cliente
y abre sesión nueva.
cp -r skill ~/.hermes/skills/bilbao-avisos # Hermes
cp -r skill ~/.claude/skills/bilbao-avisos # Claude Code
# o descárgala: https://github.com/Naroh091/bilbao-avisos-mcp/blob/main/skill/SKILL.mdInstálalo así (requiere Node 18+):
Credenciales: las de la propia app (
BILBAO_AVISOS_USERNAME=999400,BILBAO_AVISOS_PASSWORD=s7rvq45XJ2) en el entorno del servidor. Sin ellas solo funcionan las llamadas sin auth (categorías, callejero).Instalación según tu cliente (comandos exactos): Claude Code (
claude mcp add … -- npx -y bilbao-avisos-mcp), Hermes (hermes mcp add … --command npx … --args -y bilbao-avisos-mcp) u OpenClaw (openclaw mcp add … --command npx --arg -y --arg bilbao-avisos-mcp). Las credenciales viajan en el entorno de tu config.Identidad: pregunta idioma + nombre + primer apellido + teléfono o email UNA vez y guárdala con
set_identity(verifica conget_identity). Sin identidad no se puede crear ni consultar.Verifica (
mcp list/test/doctor --probesegún cliente): debes ver 12 tools.Uso: hay skill completa en
skill/SKILL.md. Lo esencial: solo incidencias genuinas;create_aviso_from_photoen fases (categoría → calle → preview → envío solo con "sí" humano +confirm+human_confirmed+preview_token); foto porfile_id; sin GPS no adivines la ubicación; calle y portal siempre desearch_street.
Añadir el MCP vía npx
Requiere Node 18+.
Claude Code
claude mcp add bilbao-avisos -e BILBAO_AVISOS_USERNAME=999400 -e BILBAO_AVISOS_PASSWORD=s7rvq45XJ2 -- npx -y bilbao-avisos-mcp
claude mcp list # verificarHermes
hermes mcp add bilbao-avisos --command npx --env BILBAO_AVISOS_USERNAME=999400 --env BILBAO_AVISOS_PASSWORD=s7rvq45XJ2 --args -y bilbao-avisos-mcp
hermes mcp test bilbao-avisos # verificar (lista las 12 tools)OpenClaw
openclaw mcp add bilbao-avisos \
--command npx \
--arg -y \
--arg bilbao-avisos-mcp \
--env BILBAO_AVISOS_USERNAME=999400 \
--env BILBAO_AVISOS_PASSWORD=s7rvq45XJ2
openclaw mcp doctor bilbao-avisos --probe # verificarDesde código
npm install
npm run build
npx -y -p bilbao-avisos-mcp bilbao-avisos-mcp-http # HTTP en 127.0.0.1:3000/mcpHerramientas MCP
Tool | Qué hace |
| Token Keycloak + |
| Identidad guardada del comunicante (o null). |
| Guarda nombre/apellidos/contacto/idioma (se pregunta una vez). |
| Servicios y temas (cada tema trae su |
| Detalle de un |
| Sugiere |
| Callejero: calle → |
| lon/lat → calle y portal cercanos. |
| Comunicaciones del comunicante (por teléfono/email). |
| Crea un aviso/sugerencia. Dry-run por defecto; |
| Aviso desde foto en fases: categoría → calle → preview (GPS EXIF) y envío solo con |
| Adjunta una foto a la comunicación ( |
Son 12 tools.
Seguridad de envío
create_aviso es dry-run por defecto: devuelve el payload sin crear nada. Solo con
confirm: true hace los POST reales — un aviso real que revisa personal municipal.
Envía únicamente incidencias reales.
create_aviso_from_photo exige confirmación humana en fases:
Categoría (sin
serviceCode): sugiere y no envía nada.Calle (sin
streetCode): pide calle/portal y no envía nada.Preview (
confirmausente/false): GPS EXIF (olat/lngmanuales), payload +preview_token. No envía nada.Envío: el agente muestra el preview al humano y espera su "sí"; solo entonces repite la llamada con los MISMOS campos +
confirm: true+human_confirmed: true+preview_token. Si cambió cualquier campo, hay que repetir el preview.
Uso como CLI
export BILBAO_AVISOS_USERNAME=999400 BILBAO_AVISOS_PASSWORD=s7rvq45XJ2
node dist/cli.js check-auth
node dist/cli.js identity-set "Nombre" "Apellido1" "" 944000000 nombre@example.com es
node dist/cli.js categories
node dist/cli.js category LIM-OSLILI
node dist/cli.js street "Gran Via"
node dist/cli.js reverse -2.9234 43.2642
node dist/cli.js my-avisos
node dist/cli.js create A LIM-OSLILI 4040 1 "Contenedor desbordado" # dry-run
node dist/cli.js create A LIM-OSLILI 4040 1 "Contenedor desbordado" --send # ENVÍA de verdad
node dist/cli.js from-photo foto.jpg LIM-OSLILI "Cartones en la acera" # preview desde foto
node dist/cli.js prep-photo foto.jpg [foto-ligera.jpg] # reduce para el modelo, conserva EXIF/GPSServidor HTTP (opcional)
Por stdio cada uno corre su copia con sus credenciales. La entrada HTTP sirve para el caso contrario: exponer el servidor que corre en TU máquina (con TUS credenciales) para que un agente en OTRA máquina lo use — en ese caso actúa como tú, no como el dueño del agente remoto. Para uso personal normal no la necesitas.
export BILBAO_AVISOS_USERNAME=999400 BILBAO_AVISOS_PASSWORD=s7rvq45XJ2
export BILBAO_AVISOS_MCP_SECRET=<un-secreto-largo> # exige x-mcp-secret o Bearer
export BILBAO_AVISOS_ALLOWED_HOSTS=tu-host.tu-tailnet.ts.net # anti DNS-rebinding
npm run start:http # 127.0.0.1:3000/mcpVariables: BILBAO_AVISOS_HTTP_PORT (3000), BILBAO_AVISOS_HTTP_HOST (127.0.0.1),
BILBAO_AVISOS_HTTP_PATH (/mcp). Expón solo en red privada (p.ej. tailscale serve,
nunca funnel): quien llegue a la URL actúa como tu usuario. Para persistencia,
launchd/pm2/tmux o similar.
Arquitectura
src/client.ts— HTTP: token Keycloak (grant password, auto-renovación ante 401) + Bearer, callejero sin auth.src/identity.ts— perfil del comunicante en JSON local (0600), con las reglas del formulario.src/avisos.ts— núcleo de negocio (reutilizado por MCP y CLI): versión, categorías, callejero, mis avisos, creación en 2 POST (persona + comunicación), foto.src/photo.ts— foto: EXIF/GPS, subida a tmp, token de preview.src/types.ts— esquemas zod de entrada + payload de creación.src/mcp.ts—buildServer(): registra las 12 tools (compartido por stdio y HTTP).src/server.ts— entrada stdio ·src/http.ts— entrada HTTP (/mcp+PUT /upload) ·src/cli.ts— CLI.
Notas
Ingeniería inversa del APK "Mejora Bilbao - Bilbo Hobetuz" v4.0.0 + verificación en vivo de los endpoints de lectura y del dry-run (sin crear avisos reales).
Si el Ayuntamiento rota la cuenta de servicio, actualiza las variables de entorno.
Licencia
AGPLv3. Ver LICENSE.
Available Tools
12 toolsattach_photoA
Adjunta una foto a una comunicación ya creada (ide_comunicacion de la respuesta del envío). Foto por file_id (PUT /upload), image_path local o image_base64. Dry-run por defecto; confirm=true para subirla.
Inputs: ide_comunicacion (required), confirm, file_id, image_path, +1 more.
check_authA
Comprueba la cuenta de servicio: pide token Keycloak y llama a comprobarVersion. Úsalo para verificar la instalación.
Inputs: no named parameters.
create_avisoA
Crea un aviso/sugerencia. IMPORTANTE: por defecto es DRY-RUN (confirm=false) y solo devuelve el payload que se enviaría, SIN crear nada. Para crear de verdad hay que pasar confirm=true. Usa la identidad guardada salvo que se pase 'identity'.
Inputs: kind (required), streetCode (required), description (required), serviceCode (required), +9 more.
create_aviso_from_photoA
Aviso desde una FOTO en fases. VÍA PREFERIDA: sube la foto con PUT /upload (curl) y pasa file_id; por stdio usa image_path local. Fase 1: sin service_code → sugiere categorías (need_category). Fase 2: sin calle → pide calle/portal (need_street, con reversa del GPS). Fase 3 (confirm=false): preview + preview_token SIN enviar. Fase 4: MISMOS campos + confirm:true + human_confirmed:true + preview_token (tras 'sí' humano). Sin las tres NO se envía.
Inputs: x, y, lat, lng, +17 more.
get_categoryC
Detalle de un serviceCode 'SERVICIO-TEMA': servicio, tipo (A aviso / S sugerencia) y tema.
Inputs: service_code (required).
get_identityA
Devuelve la identidad del comunicante guardada (nombre, apellidos, contacto, idioma) o null si aún no se preguntó.
Inputs: no named parameters.
list_categoriesB
Servicios y temas de avisos (categorías municipales). Cada tema trae su serviceCode 'SERVICIO-TEMA' para crear avisos.
Inputs: no named parameters.
my_avisosC
Comunicaciones del comunicante (filtra por su teléfono/email guardados; se pueden sobrescribir para la llamada).
Inputs: userEmail, userPhone.
reverse_geocodeA
Calle y portal cercanos a unas coordenadas WGS84 (lon/lat, p.ej. del GPS de la foto).
Inputs: lat (required), lon (required).
search_streetB
Busca una calle en el callejero municipal. Devuelve candidatos con TECA_COD_CALLE, portales (TEPO_DIR_PORTAL), barrio/distrito y coordenadas X/Y del portal.
Inputs: query (required).
set_identityA
Guarda la identidad del comunicante (se pregunta UNA vez tras la instalación y se reutiliza). Valida: nombre y primer apellido obligatorios; teléfono o email obligatorios.
Inputs: lang (required), name (required), apellido1 (required), apellido2, +2 more.
suggest_categoriesB
Sugiere serviceCodes por palabras (p.ej. 'cartones apilados en acera').
Inputs: hint.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 12 tools
Most tools target distinct resources/actions (identity get/set, category list/get/suggest, street search vs coordinate reverse-geocode). The main overlap is create_aviso vs create_aviso_from_photo, which both create reports but differ by photo workflow, so some misselection is possible. get_category vs list_categories vs suggest_categories are also related but have distinguishable purposes.
Almost all tools follow a consistent verb_noun snake_case pattern (check_auth, get_identity, set_identity, list_categories, create_aviso, attach_photo). The main deviation is 'my_avisos' (noun-only, no verb) and the mixed English/Spanish vocabulary (categories vs avisos), but readability stays high.
12 tools is well within the ideal 3-15 range and each one covers a distinct facet of the reporting workflow (auth, identity, categories, geocoding, listing, creating, photo attachment). No obvious filler or redundant tools bloat the set.
The surface covers auth, identity, categories, geocoding, listing, creation, and photo attachment, but lacks lifecycle operations: no get_aviso for a single report's detail/status, no update/edit, and no cancel/delete. Agents can create and list but cannot inspect or modify an individual aviso, which is a notable gap.
Maintenance
Related MCP Connectors
Resolve any government entity worldwide and submit service requests. Open civic data for AI agents.
Provides access to Civic Plus - See Click Fix, allowing you to interact with your data via an LLM.…
Mobility, geocoding and nearby urban services for AI agents.
Local government intelligence for AI agents.
Related MCP Servers
- AlicenseBqualityCmaintenanceEnables an AI agent to list municipal services and categories, query existing reports, and create new reports to the Las Palmas de Gran Canaria city council—including from a photo—with human confirmation before submission.816 npm3AGPL 3.0
- AlicenseBqualityCmaintenanceEnables AI agents to report street incidents to Valencia City Council by listing categories, geocoding streets, checking existing reports, and creating nuevos avisos from text or photos with human-confirmed previews. Supports stdio and HTTP transports, with identity and device registration handled locally.1116 npm1AGPL 3.0
- AlicenseBqualityCmaintenanceEnables an AI agent to list the incident categories of Gijón's municipal reporting system and file real service notices on a citizen's behalf, including generating one from a photo by reading its EXIF GPS and suggesting the matching category. Report creation is dry-run by default and only sends after explicit human confirmation, using a saved email as the contact identity and no credentials.718 npmAGPL 3.0
- AlicenseAqualityBmaintenanceEnables an AI agent to file municipal incidents and street-damage reports with a GECOR-based town council, attaching a photo (extracting GPS from EXIF when present), previewing the exact summary for explicit human confirmation before anything is sent, and listing previously registered reports and their status. It also supports choosing official categories, resolving nearby streets or callejero references, and switching between GECOR municipalities.7MIT