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.

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.

# 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

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

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

• 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.

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

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

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

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.

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

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

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!

• 🔌 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

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

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

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

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"

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

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

• UnsupportedClassVersionError: You're running an older Java version

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

• 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

• 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

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

Solution: Set the required environment variables before running:

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

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

export UBERALL_ACCESS_TOKEN="your_valid_token"

Solution: Use system Gradle instead:

gradle build
gradle shadowJar

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

Solution: Use ISO 8601 format with timezone:

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

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.

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

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

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

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

MIT License © 2025 Uberall GmbH

• 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