🚀 Uberall MCP Server

A Model Context Protocol (MCP) server that integrates with the Uberall API, enabling AI assistants to seamlessly manage business listings, locations, and social media presence across multiple platforms.

🎯 What is MCP?

The Model Context Protocol allows AI assistants like Claude, Cursor, or VS Code Copilot to connect to external tools and data sources. This server acts as a bridge between AI assistants and the powerful Uberall platform.

This enables seamless integration with LLMs like Claude, Cursor, or Language Model APIs for comprehensive business management workflows.

🐳 Docker Support

Using the pre-built Docker image (Recommended)

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

🧠 Use With Claude Desktop

Configure in your 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"
      }
    }
  }
}

🧠 Use With Other MCP Clients (Cursor, VS Code, etc.)

For other MCP-compatible tools using Docker, use this configuration:

1. Create an mcp.json file in your project:

touch mcp.json

2. Add the following configuration to the file:

{
  "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"
      }
    }
  }
}

3. Save the file and restart your IDE/tool. You should now be able to access all the tools!

✨ Features

• 🔌 MCP Protocol Compliant - Works with any MCP-compatible AI assistant
• 🏢 Business Management - Find and manage your business listings
• 📍 Location Management - Access and manage location data
• 📱 Social Media Integration - Create posts across multiple platforms (Google, Facebook, etc.)
• 🔍 Advanced Search - Filter businesses, locations, and social posts
• 🐳 Docker Ready - Pre-built multi-platform Docker images
• ⚡ Fast & Lightweight - Built with Kotlin coroutines for optimal performance

🛠️ Available Tools

The MCP server provides the following tools for interacting with the Uberall API:

find_businesses

Find businesses that the user has access to. Business IDs can be used to create social posts and find locations.

Parameters:

• query (required): Search query to filter by name, street address, ZIP, city, country, or identifier

Returns: List of businesses with their IDs and names

find_locations

Find locations that belong to businesses. Location IDs are required for creating social posts.

Parameters:

• query (optional): Filter locations by various fields
• businessIds (optional): Array of business IDs to filter locations

Returns: List of locations with IDs, names, business information, and city Note: Location IDs returned should be used in create_social_post unless specified otherwise

create_social_post

Create a social media post for specified locations and platforms.

Parameters:

• title (optional): Post title (defaults to "Social Post")
• description (required): Post content/description
• directories (required): Array of social platforms in UPPERCASE (e.g., ["GOOGLE", "FACEBOOK"])
• publicationDate (required): ISO 8601 date string (YYYY-MM-dd'T'HH:mm:ssXXXXX)
• locations (required): Array of location IDs from find_locations

Returns: Created social post object with platform-specific links and status

search_social_posts

Search and filter existing social posts accessible by the user.

Parameters (all optional):

• max: Maximum number of posts to return (default: 50)
• offset: Pagination offset (default: 0)
• locationIds: Array of location IDs to filter by
• businessIds: Array of business IDs to filter by
• statuses: Array of post statuses: ["SCHEDULED", "ACTIVE", "APPROVAL_NEEDED", "ENDED"]
• directories: Array of social platforms in UPPERCASE
• minPublicationDate: Minimum date filter (YYYY-MM-dd)
• maxPublicationDate: Maximum date filter (YYYY-MM-dd)

Returns: Array of social posts matching the filter criteria

📚 Examples

Basic Usage with Claude Desktop

Once configured, you can use natural language to interact with your Uberall data:

"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

Typical Workflow

1. Find your businesses: "Show me my business listings"
2. Get locations: "What locations do I have for [business name]?"
3. Create social posts: "Create a promotional post for Black Friday at all my retail locations"
4. Monitor posts: "Show me all scheduled social posts for this week"

🔧 Error Handling

The server implements comprehensive error handling with clear, actionable error messages:

Configuration Errors

• Missing Environment Variables: Clear messages indicating which variables are required
• Invalid URLs: Validation of Uberall API endpoints

Java Version Issues

• UnsupportedClassVersionError: You're running an older Java version
  Copy

  # 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/

Validation Errors

• Required Parameters: Specific messages for missing required tool parameters
• Date Format Errors: Clear guidance on expected date formats (ISO 8601)
• Empty Arrays: Validation that required arrays contain at least one item

API Errors

• Authentication: Clear messages for invalid access tokens
• Network Issues: Timeout and connectivity error handling
• Rate Limiting: Proper handling of API rate limits with retry logic

Example Error Response

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

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Quick Development Setup

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

📄 License

MIT License © 2025 Uberall GmbH

🔗 Links

• Model Context Protocol - Learn more about MCP
• Claude Desktop - AI assistant with MCP support
• Uberall API Documentation - Official API docs
• GitHub Issues - Report bugs or request features

🚀 Quick Start

📦 Option 1: Download Pre-built JAR

# 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

🐳 Option 2: Use 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

🛠️ Option 3: Build from Source

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

�️ Detailed Setup

Prerequisites

• Java 17 or higher (verify with java -version)
• Docker (alternative to Java installation)
• Gradle (only if building from source)

⚠️ Important: This server requires Java 17+. If you get UnsupportedClassVersionError, you're running an older Java version. Use java -version to check your version.

Required Environment Variables

Before running the server, you must set these environment variables:

• UBERALL_URL (required): Your Uberall API base URL
  • Production: https://uberall.com
  • Sandbox: https://sandbox.uberall.com
• UBERALL_ACCESS_TOKEN (required): Your Uberall API access token

Get Your Uberall API Access Token:

To obtain your API access token, follow the official Uberall documentation: 📖 API Authentication Guide

📦 Installation Options

Download the latest JAR from GitHub Releases:

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

Manual download:

1. Visit GitHub Releases
2. Download uberall-mcp-server.jar from the latest release

Then run:

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

🧠 Configure with AI Tools

Claude Desktop

Add to your 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"
      }
    }
  }
}

Other MCP Clients (Cursor, VS Code, etc.)

For other MCP-compatible tools, you can use this general configuration approach:

1. Create an mcp.json file in your project:

touch mcp.json

2. Add the following configuration to the file:

{
  "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"
      }
    }
  }
}

3. Save the file and restart your IDE/tool. You should now be able to access all the tools!

Other MCP Clients: List of popular MCP clients are available here.

💡 Tip: Replace /path/to/uberall-mcp-server.jar with the actual path where you downloaded the JAR file.

🔍 Troubleshooting

Common Issues

"Configuration Error: UBERALL_URL environment variable is required"

Solution: Set the required environment variables before running:

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

"Error: UBERALL_ACCESS_TOKEN environment variable is required"

Solution: Ensure your access token is valid and properly set:

export UBERALL_ACCESS_TOKEN="your_valid_token"

Build fails with Gradle wrapper error

Solution: Use system Gradle instead:

gradle build
gradle shadowJar

Docker container fails to start

Solution: Ensure environment variables are passed correctly:

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

"Invalid publication date format" error

Solution: Use ISO 8601 format with timezone:

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

Empty response from API calls

Possible causes:

• Invalid access token
• No permissions for requested resources
• Network connectivity issues
• API endpoint temporarily unavailable

Solution: Check your access token permissions and network connectivity.

Debug Mode

For additional debugging information, check the application logs for detailed error messages and stack traces.

Getting Help

If you encounter issues not covered here:

1. Check your environment variable configuration
2. Verify your access token has the required permissions
3. Ensure you're using a supported Uberall API endpoint
4. Check the application logs for detailed error information