Uberall MCP Server

Integrates with the Uberall API to manage business listings, locations, and social media presence.

⚠️ Deprecated — use the hosted Uberall Platform MCP server instead

This project is deprecated and no longer maintained.It was a localstdioMCP server that ran on your machine and called the Uberall API with your API key. It has been replaced by thehosted Uberall Platform MCP server— remote, OAuth-capable, and requiring no local installation.

- Endpoint:https://mcp.uberall.com/mcp(remote, streamable HTTP)
- Documentation & setup:https://docs.uberall.com/guides/platform-mcp
- Authentication:OAuth 2.0 for standard users, or anAuthorization: Bearer <API_KEY>header forAPI_ADMINusers

claude mcp add-json uberall '{"type":"http","url":"https://mcp.uberall.com/mcp"}'

claude mcp add-json uberall '{"type":"http","url":"https://mcp.uberall.com/mcp","headers":{"Authorization":"Bearer UBERALL_API_KEY"}}'

This repository isarchived (read-only)and kept only for historical reference. No further updates, fixes, or releases will be published here. Questions:api@uberall.com

# 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

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

Download the latest JAR fromGitHub Releases:

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

- VisitGitHub Releases
- Downloaduberall-mcp-server.jarfrom the latest release

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

{ "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 anmcp.jsonfile 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 availablehere.

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

{ "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 anmcp.jsonfile 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.

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

- 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 cityNote:Location IDs returned should be used increate_social_postunless specified otherwise

Create a social media post for specified locations and platforms.

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

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

Search and filter existing social posts accessible by the user.

- 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

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

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:

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

Solution:Check your access token permissions and network connectivity.