Uberall

You use this MCP server to connect an AI assistant to the Uberall platform, enabling you to manage business listings, locations, and social posts across multiple channels through natural, conversational interactions.

How to use

You run the Uberall MCP Server as a local process or via Docker and connect your MCP-enabled AI agent or IDE client to it. Once connected, you can find your businesses, locate their locations, and create or search social posts across platforms like Google and Facebook. Use natural language prompts to perform workflows such as locating a business, selecting its locations, drafting a promotional post, and monitoring post statuses.

How to install

Prerequisites: Install Java 17 or higher and ensure your system can run Docker if you plan to use the containerized approach.

Option A: Download the pre-built JAR and run directly

# 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 B: 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 C: 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

Install notes and prerequisites

• Ensure Java 17 or higher is installed and available in your PATH. Check with java -version.

• If you plan to run via Docker, Docker must be installed and running on your machine.

Environment variables you must set

Before starting the server, define these environment variables:

• UBERALL_URL: Your Uberall API base URL (production: https://uberall.com, sandbox: https://sandbox.uberall.com)

• UBERALL_ACCESS_TOKEN: Your Uberall API access token

Configure with MCP clients

Claude Desktop example configuration to connect to the Uberall MCP Server:

{
  "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 clients (Cursor, VS Code, etc.), create an mcp.json with a stdio configuration that launches the server and passes the necessary environment variables. An example configuration is shown here for reference.

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

Security and best practices

Keep your access token secure. Do not commit tokens into version control. Prefer storing tokens in your environment or a secrets manager and reference them at runtime.

Troubleshooting

Common issues include missing environment variables, invalid tokens, or Java version mismatches. Verify you are running Java 17+ and that UBERALL_URL and UBERALL_ACCESS_TOKEN are correctly set.

If the server fails to start in Docker, ensure you pass the environment variables correctly to the container.

For ISO 8601 date formats in scheduling, use an exact timestamp with timezone, e.g., 2024-12-06T14:30:00+01:00.

Notes

The MCP server provides tools to find businesses, locate their locations, create social posts, and search existing posts. Use these endpoints through your MCP client to perform end-to-end workflows.

Available tools

find_businesses

Find businesses the user has access to; returns IDs and names for further actions.

find_locations

Find locations for given businesses; returns IDs and related info necessary for posting.

create_social_post

Create a social media post for specified locations and platforms with a given publication date.

search_social_posts

Search and filter existing social posts by location, business, status, and date range.