🚀 Servidor MCP Uberall

Un servidor de Protocolo de Contexto de Modelo (MCP ) que se integra con la API de Uberall, lo que permite a los asistentes de IA gestionar sin problemas los listados de negocios, ubicaciones y presencia en redes sociales en múltiples plataformas.

🎯 ¿Qué es el MCP?

El Model Context Protocol permite a los asistentes de IA como Claude, Cursor o VS Code Copilot conectarse a herramientas externas y fuentes de datos. Este servidor actúa como puente entre los asistentes de IA y la potente plataforma Uberall.

Esto permite una integración perfecta con LLMs como Claude, Cursor, o APIs de modelos de lenguaje para flujos de trabajo integrales de gestión empresarial.

🚀 Inicio rápido

📦 Opción 1: Descargar JAR preconstruido

# Descarga la última versión curl -L -o uberall-mcp-server.jar https://github.com/uberall/uberall-mcp-server/releases/latest/download/uberall-mcp-server.jar # Configura tus credenciales export UBERALL_URL="https://sandbox.uberall.com" export UBERALL_ACCESS_TOKEN="tu_acceso_token_aquí" # Ejecuta el servidor java -jar uberall-mcp-server.jar

🐳 Opción 2: Utilizar Docker

export UBERALL_URL="https://sandbox.uberall.com" export UBERALL_ACCESS_TOKEN="your_access_token_here" docker run --rm -i -e UBERALL_ACCESS_TOKEN -e UBERALL_URL uberall/uberall-mcp-server:latest

🛠️ Opción 3: Construir desde el código fuente

git clone https://github.com/uberall/uberall-mcp-server.git cd uberall-mcp-server ./gradlew shadowJar export UBERALL_URL="https://sandbox.uberall.com" export UBERALL_ACCESS_TOKEN="your_access_token_here" java -jar build/libs/uberall-mcp-server.jar

configuración detallada

Requisitos previos

Java 17 o superior (verifíquelo con java -version)
Docker (alternativa a la instalación de Java)
Gradle (sólo si se construye desde el código fuente)

⚠️ Importante: Este servidor requiere Java 17+. Si obtiene UnsupportedClassVersionError, está ejecutando una versión anterior de Java. Utilice java -version para comprobar su versión.

Variables de entorno necesarias

Antes de ejecutar el servidor, debe configurar estas variables de entorno:

UBERALL_URL(obligatorio): Su URL base de la API Uberall
- Producción: https://uberall.com
- Sandbox: https://sandbox.uberall.com
UBERALL_ACCESS_TOKEN(obligatorio): Tu token de acceso a la API de Uberall

Obtén tu token de acceso a la API de Uberall:

Para obtener tu token de acceso a la API, sigue la documentación oficial de Uberall: 📖 Guía de autenticación de la API

📦 Opciones de instalación

Descarga el JAR más reciente de GitHub Releases:

curl -L -o uberall-mcp-server.jar https://github.com/uberall/uberall-mcp-server/releases/latest/download/uberall-mcp-server.jar

Descarga manual:

Visite GitHub Releases
Descarga uberall-mcp-server. jar de la última versión

A continuación, ejecute:

# Establecer variables de entorno export UBERALL_URL="https://sandbox.uberall.com" export UBERALL_ACCESS_TOKEN="your_access_token_here" java -jar uberall-mcp-server.jar

🧠 Configurar con herramientas AI

Escritorio Claude

Añade a tu claude_desktop_config.json:

{ "mcpServers": { "uberall-mcp-server": {"command": ["java", "-jar", "/ruta/a/uberall-mcp-server.jar"], "env": {"UBERALL_ACCESS_TOKEN": "your_access_token_here", "UBERALL_URL": "https://sandbox.uberall.com" } } }

Otros clientes MCP (Cursor, VS Code, etc.)

Para otras herramientas compatibles con MCP, puede utilizar este enfoque de configuración general:

Cree un archivo mcp.json en su proyecto:

touch mcp.json

Añada la siguiente configuración al archivo

{ "mcpServers": { "uberall-mcp-server": { "command": "java", "args": ["-jar", "/ruta/a/uberall-mcp-server.jar"], "type": "stdio", "env": { "UBERALL_ACCESS_TOKEN": "your_access_token_here", "UBERALL_URL": "https://sandbox.uberall.com" } } }

Guarde el archivo y reinicie su IDE/herramienta. Ahora debería poder acceder a todas las herramientas

Otros clientes MCP: Lista de clientes MCP populares están disponibles aquí.

💡 Consejo: Reemplace /path/to/uberall-mcp-server.jar con la ruta real donde descargó el archivo JAR.

🐳 Soporte Docker

Utilizando la imagen pre-construida de Docker (Recomendado)

export UBERALL_ACCESS_TOKEN="your_access_token_here" export UBERALL_URL="https://sandbox.uberall.com" docker run --rm -i -e UBERALL_ACCESS_TOKEN -e UBERALL_URL uberall/uberall-mcp-server:latest

🧠 Uso con Claude Desktop

Configure en su claude_desktop_config.json:

{ "mcpServers": { "uberall-mcp-server": { "command": [ "docker", "run", "--rm", "-i", "-e", "UBERALL_ACCESS_TOKEN", "-e", "UBERALL_URL", "uberall/uberall-mcp-server:latest" ], "env": { "UBERALL_ACCESS_TOKEN": "your_access_token_here", "UBERALL_URL": "https://sandbox.uberall.com" } } }

🧠 Uso con otros clientes MCP (Cursor, VS Code, etc.)

Para otras herramientas compatibles con MCP que utilicen Docker, utilice esta configuración:

Crea un archivo mcp.json en tu proyecto:

touch mcp.json

Añada la siguiente configuración al archivo

{ "mcpServers": { "uberall-mcp-server": { "command": "docker", "args": ["run", "--rm", "-i", "-e", "UBERALL_ACCESS_TOKEN", "-e", "UBERALL_URL", "uberall/uberall-mcp-server:latest"], "type": "stdio", "env": { "UBERALL_ACCESS_TOKEN": "your_access_token_here", "UBERALL_URL": "https://sandbox.uberall.com" } } }

Guarde el archivo y reinicie su IDE/herramienta. ¡Ahora deberías poder acceder a todas las herramientas!

✨ Características

🔌 C ompatible con el protocolo MCP - Funciona con cualquier asistente de IA compatible con MCP
🏢 Gestión de negocios - Encuentra y gestiona los listados de tu negocio
📍 Gestión de ubicaciones - Accede y gestiona los datos de ubicación
📱 Integración con redes sociales - Crea publicaciones en múltiples plataformas (Google, Facebook, etc.)
🔍 Búsqueda avanzada - Filtra negocios, ubicaciones y publicaciones sociales
🐳 Docker Ready - Imágenes Docker multiplataforma preconstruidas
⚡ Rápido y ligero - Construido con coroutines Kotlin para un rendimiento óptimo

🛠️ Herramientas disponibles

El servidor MCP proporciona las siguientes herramientas para interactuar con la API Uberall:

`find_businesses`

Encuentra negocios a los que el usuario tiene acceso. Los ID de negocios se pueden utilizar para crear publicaciones sociales y encontrar ubicaciones.

Parámetros:

query(obligatorio): Consulta de búsqueda para filtrar por nombre, dirección postal, código postal, ciudad, país o identificador

Devuelve: Lista de negocios con sus identificadores y nombres

`buscar_localizaciones`

Buscar ubicaciones que pertenezcan a empresas. Los ID de ubicación son necesarios para crear publicaciones sociales.

Parámetros:

query(opcional): Filtrar ubicaciones por varios campos
businessIds(opcional): Matriz de ID de negocios para filtrar las ubicaciones

Devuelve: Lista de ubicaciones con IDs, nombres, información del negocio y ciudadNota: Los IDs de ubicación devueltos deben usarse en create_social_post a menos que se especifique lo contrario

`create_social_post`

Crea una publicación en redes sociales para las ubicaciones y plataformas especificadas.

Parámetros:

title(opcional): Título de la publicación (por defecto es "Social Post")
description(obligatorio): Contenido/descripción de la publicación
directorios(obligatorio): Conjunto de plataformas sociales en MAYÚSCULAS (por ejemplo, ["GOOGLE", "FACEBOOK"])
publicationDate(obligatorio): Cadena de fecha ISO 8601 (AAAA-MM-dd'T'HH:mm:ssXXXXX)
locations(obligatorio): Matriz de ID de ubicación de find_locations

Devuelve: Objeto de publicación social creado con enlaces y estado específicos de la plataforma

`search_social_posts`

Busca y filtra las publicaciones sociales existentes accesibles por el usuario.

Parámetros (todos opcionales):

max: Número máximo de posts a devolver (por defecto: 50)
offset: Desplazamiento de paginación (por defecto: 0)
locationIds: Matriz de IDs de ubicación por los que filtrar
businessIds: Matriz de IDs de negocio por los que filtrar
estados: Matriz de estados de publicación: ["PROGRAMADO", "ACTIVO", "APROBACIÓN_NECESARIA", "FINALIZADO"]
directorios: Matriz de plataformas sociales en MAYÚSCULAS
minPublicationDate: Filtro de fecha mínima (AAAA-MM-dd)
maxPublicationDate: Filtro de fecha máxima (AAAA-MM-dd)

Devuelve: Array de publicaciones sociales que coinciden con los criterios del filtro

📚 Ejemplos

Uso básico con Claude Desktop

Una vez configurado, puedes usar lenguaje natural para interactuar con tus datos de Uberall:

"Encuentra todas las ubicaciones de mis cafeterías en Berlín" → Utiliza find_businesses + find_locations "Crea un post de promoción navideña para todos mis restaurantes, programado para el 25 de diciembre" → Utiliza find_businesses + find_locations + create_social_post "Muéstrame todos mis posts sociales del mes pasado que aún están activos" → Utiliza search_social_posts con filtros de fecha

Flujo de trabajo típico

Encuentra tus negocios: "Muéstrame los anuncios de mis negocios"
Obtén ubicaciones: "¿Qué ubicaciones tengo para [nombre del negocio]?"
Crear posts sociales: "Crear un post promocional para el Black Friday en todos mis locales comerciales"
Supervisar publicaciones: "Muéstrame todos los posts sociales programados para esta semana"

gestión de errores

El servidor implementa un manejo integral de errores con mensajes de error claros y procesables:

Errores de configuración

Variables de entorno que faltan: Mensajes claros que indican qué variables son necesarias
URLs no válidas: Validación de los puntos finales de la API Uberall

Problemas de versión de Java

UnsupportedClassVersionError: Está ejecutando una versión antigua de Java

# Compruebe su versión de Java java -version # Debería mostrar la versión 17.x.x o superior # Si ve la versión 8, 11, etc., instale Java 17+ # macOS: brew install openjdk@17 # Ubuntu: apt install openjdk-17-jre # Windows: Descargar desde https://adoptium.net/

Errores de validación

Parámetros requeridos: Mensajes específicos en caso de que falten parámetros obligatorios de la herramienta
Errores de formato de fecha: Orientación clara sobre los formatos de fecha esperados (ISO 8601)
Matrices vacías: Validación de que las matrices requeridas contienen al menos un elemento

Errores de API

Autenticación: Mensajes claros para tokens de acceso no válidos
Problemas de red: Gestión de tiempos de espera y errores de conectividad
Limitación de velocidad: Gestión adecuada de los límites de velocidad de la API con lógica de reintento

Ejemplo de respuesta de error

{ "isError": true, "content": [ { "type": "text", "text": "Error: Publication date is required" } } }

🔍 Solución de problemas

Problemas comunes

"Error de configuración: Se requiere la variable de entorno UBERALL_URL"

Solución: Establezca las variables de entorno necesarias antes de ejecutar:

export UBERALL_URL="https://sandbox.uberall.com" export UBERALL_ACCESS_TOKEN="tu_token_aquí"

"Error: Se requiere la variable de entorno UBERALL_ACCESS_TOKEN"

Solución: Asegúrese de que su token de acceso es válido y está correctamente configurado:

export UBERALL_ACCESS_TOKEN="tu_token_valido"

La compilación falla con un error de envoltorio de Gradle

Solución: Utilice el sistema Gradle en su lugar:

gradle build gradle shadowJar

El contenedor Docker no se inicia

Solución: Asegúrese de que las variables de entorno se pasan correctamente:

docker run --rm -i -e UBERALL_ACCESS_TOKEN="$UBERALL_ACCESS_TOKEN" -e UBERALL_URL="$UBERALL_URL" uberall-mcp-server

"Error "Formato de fecha de publicación no válido

Solución: Utilice el formato ISO 8601 con la zona horaria:

2024-12-06T14:30:00+01:00

Respuesta vacía de las llamadas a la API

Posibles causas:

Token de acceso no válido
No hay permisos para los recursos solicitados
Problemas de conectividad de red
El punto final de la API no está disponible temporalmente

Solución: Compruebe los permisos del token de acceso y la conectividad de la red.

Modo de depuración

Para obtener información de depuración adicional, compruebe los registros de la aplicación para obtener mensajes de error detallados y rastros de pila.

Obtener ayuda

Si se encuentra con problemas no cubiertos aquí:

Compruebe la configuración de las variables de entorno
Compruebe que su token de acceso tiene los permisos necesarios
Asegúrese de que está utilizando un punto final de la API Uberall compatible
Compruebe los registros de la aplicación para obtener información detallada de error

🤝 Contribuir

¡Damos la bienvenida a las contribuciones! Por favor, consulte nuestra Guía de Contribución para más detalles.

Configuración rápida de desarrollo

git clone https://github.com/uberall/uberall-mcp-server.git cd uberall-mcp-server cp src/test/resources/test-config-example.properties src/test/resources/test-config.properties # Edita test-config.properties con tus credenciales de prueba ./gradlew test

📄 Licencia

enlaces

Protocolo de contexto de modelo - Más información sobre MCP
Claude Desktop - Asistente de inteligencia artificial compatible con MCP
Documentación de la API de Uberall - Docs oficiales de la API
GitHub Issues - Informar de errores o solicitar características

Servidor	Resumen	Acciones
Servidor MCP ArgoCD	Un servidor MCP (Model Context Protocol) que se integra con la API de ArgoCD, lo que permite a los a...	Ver
Recuperación de KB de Bedrock de AWS	Servidor MCP para acceder a las bases de conocimiento de Amazon Bedrock	Ver
Servidor MCP remoto de Cloudflare (Authless)	Este ejemplo le permite implementar un servidor MCP remoto que no requiere autenticación en Cloudfla...	Ver
Servidor MCP de Lodgify	Un servidor de Protocolo de Contexto de Modelo (MCP) para la API de alquiler vacacional de Lodgify....	Ver
CData YouTube Analytics	Servidor de protocolo de contexto de modelo (MCP) de CData para YouTube Analytics	Ver
Servidor MCP a Markdown		Ver