Preference Analytics MCP

Preference Analytics MCP Server

Model Context Protocol server for cross-platform preference analytics via BigQuery.

Quick Start

1. Install

cd preference-analytics-mcp
python -m venv venv
source venv/bin/activate  # or venv\Scripts\activate on Windows
pip install -r requirements.txt

2. Configure

cp env.example .env
# Edit .env - set GCP_PROJECT_ID

3. Test

python test_connection.py

4. Start Server

# Easy way
./start_server.sh

# Or manual
python server.py --transport sse --port 8000

Server runs on http://localhost:8000/messages

5. Configure Cursor

In Cursor Settings → Features → Model Context Protocol:

{
  "mcpServers": {
    "preference-analytics": {
      "url": "http://localhost:8000/messages"
    }
  }
}

Restart Cursor and start querying!

Available Tools

1. get_platform_synergy - Platform reach, overlap, media mix recommendations
2. get_category_correlation - Cross-platform category correlations
3. get_user_coherence - Individual user cross-platform behavior
4. get_segment_analysis - Audience segment insights
5. get_category_preferences - Top categories per platform

Example Queries (in Cursor)

• "Show me platform synergy analysis"
• "Find category correlations between Spotify and Amazon"
• "Analyze the gaming segment"
• "What are top Spotify categories?"

Predefined Segments

• all_users - All users
• multi_platform - Users on 2+ platforms
• high_engagement - Highly engaged users
• indian_entertainment - Indian content fans
• gaming - Gaming enthusiasts
• fitness - Fitness & wellness users

Command Options

# Default port
python server.py --transport sse

# Custom port
python server.py --transport sse --port 8080

# Localhost only
python server.py --transport sse --host 127.0.0.1 --port 8000

Troubleshooting

Port in use:

python server.py --transport sse --port 8001

Can't connect to BigQuery:

python test_connection.py

Cursor can't connect:

• Verify server is running
• Check URL in Cursor config
• Restart Cursor

Extending

Add New Segment

Edit analytics/segment_analysis.py:

elif segment_name == "new_segment":
    query = f"""
    SELECT DISTINCT user_id
    FROM `{self.config.get_table_id('table_name')}`
    WHERE condition = 'value'
    """

Add New Analytics Tool

1. Create module in analytics/
2. Register in server.py list_tools()
3. Add handler method

See existing modules for examples.

Requirements

• Python 3.10+
• BigQuery dataset with tables:

- preference_summary - category_preferences - user_platform_presence - unified_interest_matrix - category_mapping

License

Part of the Preference Analytics project.