RetroSearch Browse

Home - News ( United States | United Kingdom | Italy | Germany ) - Football scores

Showing content from https://github.com/uberall/uberall-mcp-server below:

uberall/uberall-mcp-server: A Model Context Protocol (MCP) server for Uberall API integration

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.

📦 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

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

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

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:

Visit GitHub Releases
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

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:

Create an mcp.json file in your project:

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

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.

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:

Create an mcp.json file in your project:

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

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

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

Find your businesses: "Show me my business listings"
Get locations: "What locations do I have for [business name]?"
Create social posts: "Create a promotional post for Black Friday at all my retail locations"
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"
    }
  ]
}

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

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

If you encounter issues not covered here:

Check your environment variable configuration
Verify your access token has the required permissions
Ensure you're using a supported Uberall API endpoint
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

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

RetroSearch is an open source project built by @garambo | Open a GitHub Issue

Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo

HTML: 3.2 | Encoding: UTF-8 | Version: 0.7.4