Uberall MCP Server

Se integra con la API de Uberall para gestionar listados de negocios, ubicaciones y presencia en redes sociales.

Documentación

[!WARNING]

⚠️ Obsoleto: use el servidor MCP alojado de Uberall Platform en su lugar

Este proyecto está obsoleto y ya no se mantiene. Era un servidor MCP local stdio que se ejecutaba en su máquina y llamaba a la API de Uberall con su clave API. Ha sido reemplazado por el servidor MCP alojado de Uberall Platform — remoto, compatible con OAuth y que no requiere instalación local.

Endpoint: https://mcp.uberall.com/mcp (remoto, HTTP transmisible)

Documentación y configuración: https://docs.uberall.com/guides/platform-mcp

Autenticación: OAuth 2.0 para usuarios estándar, o un encabezado Authorization: Bearer <API_KEY> para usuarios de API_ADMIN

Inicio rápido (Claude):
claude mcp add-json uberall '{"type":"http","url":"https://mcp.uberall.com/mcp"}'
Para acceso con clave API de API_ADMIN:
claude mcp add-json uberall '{"type":"http","url":"https://mcp.uberall.com/mcp","headers":{"Authorization":"Bearer UBERALL_API_KEY"}}'
Por qué el cambio: el servidor local stdio no podía conectarse a plataformas de agentes alojadas/remotas, que es lo que los clientes necesitan cada vez más. El servidor MCP alojado de Platform proporciona un único endpoint remoto, OAuth estándar y un catálogo de herramientas en crecimiento (Locations Hub, Listings, Social, Reviews y más).

Este repositorio está archivado (solo lectura) y se conserva únicamente como referencia histórica. No se publicarán más actualizaciones, correcciones ni versiones aquí. Preguntas: api@uberall.com

_{La documentación original a continuación se conserva solo como referencia.}

🚀 Uberall MCP Server

Un servidor Model Context Protocol (MCP) que se integra con la API de Uberall, permitiendo a los asistentes de IA gestionar sin problemas listados de negocios, ubicaciones y presencia en redes sociales en múltiples plataformas.

🎯 ¿Qué es MCP?

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

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

🚀 Inicio Rápido

📦 Opción 1: Descargar el JAR Precompilado

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

# Set your credentials
export UBERALL_URL="https://sandbox.uberall.com"
export UBERALL_ACCESS_TOKEN="your_access_token_here"

# Run the server
java -jar uberall-mcp-server.jar

🐳 Opción 2: Usar 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: Compilar 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 (verifique con java -version)
Docker (alternativa a la instalación de Java)
Gradle (solo si compila desde el código fuente)

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

Variables de Entorno Requeridas

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

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

Obtenga su Token de Acceso a la API de Uberall:

Para obtener su token de acceso a la API, siga la documentación oficial de Uberall: 📖 Guía de Autenticación de API

📦 Opciones de Instalación

Descargue el JAR más reciente desde 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
Descargue uberall-mcp-server.jar de la última versión

Luego ejecute:

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

🧠 Configurar con Herramientas de IA

Claude Desktop

Agregue a su claude_desktop_config.json:

{
  "mcpServers": {
    "uberall-mcp-server": {
      "command": ["java", "-jar", "/path/to/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 usar este enfoque de configuración general:

Cree un archivo mcp.json en su proyecto:

touch mcp.json

Agregue la siguiente configuración al archivo:

{
  "mcpServers": {
    "uberall-mcp-server": {
      "command": "java",
      "args": ["-jar", "/path/to/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: La lista de clientes MCP populares está disponible aquí.

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

🐳 Soporte Docker

Usar la imagen Docker precompilada (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

🧠 Usar 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"
      }
    }
  }
}

🧠 Usar con Otros Clientes MCP (Cursor, VS Code, etc.)

Para otras herramientas compatibles con MCP que usan Docker, use esta configuración:

Cree un archivo mcp.json en su proyecto:

touch mcp.json

Agregue 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ía poder acceder a todas las herramientas!

✨ Características

🔌 Compatible con el Protocolo MCP - Funciona con cualquier asistente de IA compatible con MCP
🏢 Gestión de Negocios - Encuentre y gestione sus listados de negocios
📍 Gestión de Ubicaciones - Acceda y gestione datos de ubicaciones
📱 Integración con Redes Sociales - Cree publicaciones en múltiples plataformas (Google, Facebook, etc.)
🔍 Búsqueda Avanzada - Filtre negocios, ubicaciones y publicaciones sociales
🐳 Listo para Docker - Imágenes Docker multiplataforma precompiladas
⚡ Rápido y Ligero - Construido con corrutinas de Kotlin para un rendimiento óptimo

🛠️ Herramientas Disponibles

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

`find_businesses`

Encuentre negocios a los que el usuario tiene acceso. Los IDs de negocios se pueden usar para crear publicaciones sociales y encontrar ubicaciones.

Parámetros:

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

Devuelve: Lista de negocios con sus IDs y nombres

`find_locations`

Encuentre ubicaciones que pertenecen a negocios. Los IDs de ubicaciones son necesarios para crear publicaciones sociales.

Parámetros:

query (opcional): Filtre ubicaciones por varios campos
businessIds (opcional): Matriz de IDs de negocios para filtrar ubicaciones

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

`create_social_post`

Cree una publicación en redes sociales para ubicaciones y plataformas específicas.

Parámetros:

title (opcional): Título de la publicación (por defecto: "Social Post")
description (obligatorio): Contenido/descripción de la publicación
directories (obligatorio): Matriz de plataformas sociales en MAYÚSCULAS (p. ej., ["GOOGLE", "FACEBOOK"])
publicationDate (obligatorio): Cadena de fecha ISO 8601 (YYYY-MM-dd'T'HH:mm:ssXXXXX)
locations (obligatorio): Matriz de IDs de ubicaciones de find_locations

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

`search_social_posts`

Busque y filtre publicaciones sociales existentes a las que el usuario tiene acceso.

Parámetros (todos opcionales):

max: Número máximo de publicaciones a devolver (por defecto: 50)
offset: Desplazamiento de paginación (por defecto: 0)
locationIds: Matriz de IDs de ubicaciones para filtrar
businessIds: Matriz de IDs de negocios para filtrar
statuses: Matriz de estados de publicación: ["SCHEDULED", "ACTIVE", "APPROVAL_NEEDED", "ENDED"]
directories: Matriz de plataformas sociales en MAYÚSCULAS
minPublicationDate: Filtro de fecha mínima (YYYY-MM-dd)
maxPublicationDate: Filtro de fecha máxima (YYYY-MM-dd)

Devuelve: Matriz de publicaciones sociales que coinciden con los criterios de filtro

📚 Ejemplos

Uso Básico con Claude Desktop

Una vez configurado, puede usar lenguaje natural para interactuar con sus datos de Uberall:

"Find all my coffee shop locations in Berlin"
→ Uses find_businesses + find_locations

"Create a holiday promotion post for all my restaurants, scheduled for December 25th"
→ Uses find_businesses + find_locations + create_social_post

"Show me all my social posts from last month that are still active"
→ Uses search_social_posts with date filters

Flujo de Trabajo Típico

Encuentre sus negocios: "Show me my business listings"
Obtenga ubicaciones: "What locations do I have for [business name]?"
Cree publicaciones sociales: "Create a promotional post for Black Friday at all my retail locations"
Supervise publicaciones: "Show me all scheduled social posts for this week"

🔧 Manejo de Errores

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

Errores de Configuración

Variables de Entorno Faltantes: Mensajes claros que indican qué variables son necesarias
URLs Inválidas: Validación de endpoints de la API de Uberall

Problemas de Versión de Java

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

# Check your Java version
java -version
# Should show version 17.x.x or higher

# If you see version 8, 11, etc., install Java 17+
# macOS: brew install openjdk@17
# Ubuntu: apt install openjdk-17-jre
# Windows: Download from https://adoptium.net/

Errores de Validación

Parámetros Obligatorios: Mensajes específicos para parámetros de herramientas obligatorios faltantes
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 obligatorias contengan al menos un elemento

Errores de API

Autenticación: Mensajes claros para tokens de acceso inválidos
Problemas de Red: Manejo de tiempos de espera y errores de conectividad
Límite de Velocidad: Manejo adecuado 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

"Configuration Error: UBERALL_URL environment variable is required"

Solución: Configure las variables de entorno requeridas antes de ejecutar:

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

"Error: UBERALL_ACCESS_TOKEN environment variable is required"

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

export UBERALL_ACCESS_TOKEN="your_valid_token"

La compilación falla con error del wrapper de Gradle

Solución: Use el Gradle del sistema en su lugar:

gradle build
gradle shadowJar

El contenedor Docker no se inicia

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

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

Error "Invalid publication date format"

Solución: Use el formato ISO 8601 con zona horaria:

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

Respuesta vacía de las llamadas a la API

Causas posibles:

Token de acceso inválido
Sin permisos para los recursos solicitados
Problemas de conectividad de red
Endpoint de API temporalmente no disponible

Solución: Verifique los permisos de su token de acceso y la conectividad de red.

Modo de Depuración

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

Obtener Ayuda

Si encuentra problemas no cubiertos aquí:

Verifique la configuración de sus variables de entorno
Verifique que su token de acceso tenga los permisos requeridos
Asegúrese de estar usando un endpoint de API de Uberall compatible
Revise los registros de la aplicación para obtener información detallada de errores

🤝 Contribuciones

¡Agradecemos las contribuciones! Consulte nuestra Guía de Contribuciones 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
# Edit test-config.properties with your test credentials
./gradlew test

📄 Licencia

🔗 Enlaces

Model Context Protocol - Aprenda más sobre MCP
Claude Desktop - Asistente de IA con soporte MCP
Documentación de la API de Uberall - Documentación oficial de la API
GitHub Issues - Reporte errores o solicite funciones