Zocialeye MCP Server

Model Context Protocol (MCP) server for the Zocialeye social media analytics API. This server provides AI assistants with access to comprehensive social media campaign analytics, including sentiment analysis, influencer tracking, and content insights across multiple platforms.

Features

This MCP server provides access to Zocialeye's comprehensive social media analytics capabilities through the following tools:

• get_campaign_categories: Get all available categories for a specific campaign

• get_campaign_keywords: Get all available keywords for a specific campaign

• get_campaign_wordcloud: Get word cloud data with sentiment analysis for a specific campaign

• get_campaign_messages: Get messages/posts with filtering and sentiment analysis for a specific campaign

• get_campaign_summary: Get summary statistics and metrics for a specific campaign

• get_campaign_influencers: Get top influencers and engagement metrics for a specific campaign

Supported Platforms

• Facebook

• X (Twitter)

• Instagram

• TikTok

• YouTube

• Forums

• Blogs

• News sites

Analytics Capabilities

• Sentiment Analysis: Positive, negative, and neutral sentiment classification

• Content Filtering: Filter by categories, groups, channels, and sentiment

• Time-based Analysis: Flexible date range filtering with hourly/daily summaries

• Engagement Metrics: Track engagement rates, influencer performance, and content reach

• Word Cloud Generation: Visual representation of trending topics and keywords

Usage

Setup with Claude Desktop

Add the following to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\\Claude\\claude_desktop_config.json

Required Environment Variables

• ZOCIALEYE_API_KEY: Your Zocialeye API key (required)

• ZOCIALEYE_CAMPAIGN_ID: Your campaign ID (required)

Available Tools

get_campaign_categories

Get all available categories for a specific campaign. Categories help organize and filter social media content by topics, brands, or themes.

Parameters:

• No parameters required. Uses ZOCIALEYE_CAMPAIGN_ID environment variable.

Returns: Array of category objects with category name and group information.

get_campaign_keywords

Get all available keywords for a specific campaign. Keywords are the tracked terms used to identify relevant social media content.

Parameters:

• No parameters required. Uses ZOCIALEYE_CAMPAIGN_ID environment variable.

Returns: Array of keyword strings.

get_campaign_wordcloud

Get word cloud data with sentiment analysis for a specific campaign. Provides visual representation of trending topics and keywords with sentiment classification.

Parameters:

• date_start (optional): Start period in ISO 8601 format (e.g., "2023-12-01T00:00:00Z"). Defaults to 1 month ago.

• date_end (optional): End period in ISO 8601 format (e.g., "2023-12-31T23:59:59Z"). Defaults to current time.

• group_by (optional): Grouping method - "category", "group", "sentiment", "keywords", or "all". Default: "all".

• filter (optional): Filter object with properties:

  • categories: Array of category names to filter by

  • sentiment: Sentiment filter - "positive", "negative", or "neutral"

  • group: Group name to filter by

  • channel: Platform filter - "facebook", "x", "instagram", "tiktok", "forum", "blog", "news", "youtube"

Returns: Word cloud data with frequency and sentiment information.

get_campaign_messages

Get messages/posts with filtering and sentiment analysis for a specific campaign. Supports pagination and sorting.

Parameters:

• date_start (optional): Start period in ISO 8601 format. Defaults to 1 month ago.

• date_end (optional): End period in ISO 8601 format. Defaults to current time.

• total (optional): Maximum number of messages to return (max 50).

• from (optional): Starting position for pagination (default: 0).

• sort_by (optional): Sorting options:

  • type: "engagement", "collected_at", or "post_time_human"

  • order: "desc" or "asc"

• group_by (optional): Grouping method - "category", "group", "sentiment", "keywords", "channel", or "all". Default: "all".

• filter (optional): Same filter options as wordcloud tool.

Returns: Array of message objects with content, metadata, and sentiment analysis.

get_campaign_summary

Get summary statistics and metrics for a specific campaign. Provides time-series data for campaign performance analysis.

Parameters:

• date_start (optional): Start period in ISO 8601 format. Defaults to 1 month ago.

• date_end (optional): End period in ISO 8601 format. Defaults to current time.

• duration (optional): Summary granularity - "hour" or "day". Default: "day".

• group_by (optional): Grouping method - "category", "group", "sentiment", "keyword", or "all". Default: "all".

• filter (optional): Same filter options as other tools.

Returns: Time-series summary data with metrics per time period.

get_campaign_influencers

Get top influencers and engagement metrics for a specific campaign. Identifies key content creators and their performance.

Parameters:

• date_start (optional): Start period in ISO 8601 format. Defaults to 1 month ago.

• date_end (optional): End period in ISO 8601 format. Defaults to current time.

• group_by (optional): Grouping method - "category", "group", "sentiment", "keyword", or "all". Default: "all".

• filter (optional): Same filter options as other tools.

Returns: Array of influencer objects with engagement metrics and performance data.

Usage Examples

Basic Campaign Analysis

Advanced Filtering and Analysis

Time-based Analysis

Troubleshooting

Common Issues

Campaign ID Required Error

• Ensure ZOCIALEYE_CAMPAIGN_ID environment variable is set

• Verify the campaign ID exists in your Zocialeye account

API Authentication Error

• Check that ZOCIALEYE_API_KEY is correctly set

• Verify the API key has proper permissions for the campaign

Date Format Errors

• Use ISO 8601 format for dates: "2023-12-01T00:00:00Z"

• Ensure dates are within valid ranges (not too far in the past/future)

Filter Parameter Issues

• Check that filter values match available options (e.g., valid sentiment values)

• Ensure category names match those returned by get_campaign_categories

GitHub Pages Login Portal

This repository also includes a GitHub Pages login portal for obtaining ZOCIALEYE_API_KEY tokens. The login page matches the WISESIGHT branding and design.

Accessing the Login Portal

Once deployed to GitHub Pages, users can access the login portal at: https://yourusername.github.io/zocialeye-mcp

Features

• Clean, Modern Design: Matches WISESIGHT branding with professional UI

• Secure Token Generation: Uses the official /generate-token API endpoint

• Token Display & Copy: Easy token retrieval with one-click copy functionality

• Error Handling: Comprehensive error messages for failed authentication

• Responsive Design: Works on desktop and mobile devices

Deployment

The login portal is automatically deployed to GitHub Pages when you push to the main branch. The deployment is handled by GitHub Actions workflow.

Manual Deployment

You can also deploy manually using:

This will:

1. Build the MCP server

2. Deploy the login portal to GitHub Pages

Getting Your API Key

1. Visit the deployed GitHub Pages URL

2. Enter your Zocialeye username and password

3. Click "Login" to generate your API token

4. Copy the generated token for use with the MCP server

Security Notes

• The login portal uses HTTPS for secure communication

• Credentials are only sent to the official Zocialeye API

• No credentials are stored or logged by the portal

• Tokens are displayed only after successful authentication

License

MIT License