adobe-cja-mcp 0.1.2

Model Context Protocol server for Adobe Customer Journey Analytics

Adobe Customer Journey Analytics MCP Server

Model Context Protocol (MCP) server for Adobe Customer Journey Analytics (CJA), enabling AI-powered analytics queries through Claude and other MCP clients.

⚡ Quick Start (Simplest Setup)

No repository cloning required! Users can run this MCP server with just 2 steps:

1. Install uv (Python package manager)

# macOS/Linux
brew install uv

# Or with curl
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

2. Configure Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "Adobe CJA": {
      "command": "uvx",
      "args": ["adobe-cja-mcp"],
      "env": {
        "ADOBE_CLIENT_ID": "your_client_id_here",
        "ADOBE_CLIENT_SECRET": "your_client_secret_here",
        "ADOBE_ORG_ID": "your_org_id@AdobeOrg",
        "ADOBE_DATA_VIEW_ID": "dv_your_dataview_id"
      }
    }
  }
}

That's it!

Restart Claude Desktop and uvx will automatically download and run the MCP server from PyPI - just like npx for Node.js!

---

Overview

This MCP server provides tools for querying Adobe CJA data, including:

• Running analytics reports with dimensions and metrics
• Multi-dimensional breakdown analysis
• Time-series trend analysis at various granularities
• Searching and filtering dimension values
• Listing available dimensions and metrics
• Data view configuration access

Features

Core Reporting Tools (MVP):

• Run ranked reports with dimensions and metrics
• Get top N items for any dimension
• List available dimensions and metrics
• Access data view configuration

Advanced Reporting:

• Breakdown Reports: Multi-dimensional analysis (e.g., pages by device type)
• Trended Reports: Time-series analysis with hourly/daily/weekly/monthly granularity
• Dimension Search: Find specific dimension values (pages, products, campaigns)
• Segment Support: Filter reports with segment IDs

Adobe CJA API Permissions

Required Permissions Scope

For this MCP server to function, your Adobe API credentials (OAuth 2.0 Server-to-Server) must have the following permissions granted in Adobe Admin Console.

Authentication Scopes

Your API credentials require these OAuth scopes:

openid
AdobeID
read_organizations
additional_info.projectedProductContext
cja.reporting         # CRITICAL - Required for all reporting operations
cja.workspace         # Required for workspace objects (projects, filters, etc.)

Critical Permissions (Required for Core Functionality)

Without these permissions, the MCP server cannot perform analytics queries:

1. CJA Reporting API - Ranked Reports

• API Endpoint: POST https://cja.adobe.io/reports
• Permission: CJA Reporting API Access
• Required For:
  • Running analytical reports with dimensions and metrics
  • Querying website performance data (sessions, page views, conversions)
  • Generating attribution analysis
  • Creating breakdown reports
• MCP Tools Blocked Without Permission:
  • cja_run_report - Main reporting tool
  • cja_get_top_items - Top performers analysis
  • cja_get_trended_report - Time-series analysis
  • cja_get_breakdown_report - Multi-dimensional breakdowns
  • cja_get_sessions_data - Session analytics
  • cja_get_conversions_data - Conversion tracking
  • cja_get_attribution_analysis - Attribution modeling
  • cja_get_funnel_analysis - Funnel analysis

2. CJA Reporting API - Top Items

• API Endpoint: GET https://cja.adobe.io/reports/topItems
• Permission: CJA Reporting API Access
• Required For:
  • Ranking dimension items by metrics
  • Finding top pages, products, campaigns
• MCP Tools Blocked Without Permission:
  • cja_get_top_items (alternative implementation)

Working Permissions (Read-Only Access)

These permissions are typically granted by default for read-only CJA API access and should already be available:

1. GET /data/dataviews/{id}/dimensions - List available dimensions
2. GET /data/dataviews/{id}/metrics - List available metrics
3. GET /data/dataviews/{id} - Get data view configuration details
4. GET /calculatedmetrics - List calculated metrics
5. GET /filters - List filters/segments
6. GET /dateranges - List date ranges
7. GET /annotations - List annotations
8. GET /projects - List Analysis Workspace projects
9. GET /data/connections - List data connections

Optional Permissions (Enhanced Features)

These permissions enable additional features but are not required for basic operation:

Individual Dimension/Metric Details

• Endpoints:
  • GET /data/dataviews/{id}/dimensions/{dimId}
  • GET /data/dataviews/{id}/metrics/{metricId}
• Benefit: Get detailed metadata for specific dimensions/metrics
• Workaround: Use list endpoints instead

Filter Validation

• Endpoint: POST /filters/validate
• Benefit: Validate filter definitions before use
• Workaround: Test filters directly in reports

List All Data Views

• Endpoint: GET /dataviews
• Benefit: Discover all available data views
• Workaround: Use configured data view ID from environment variables

Setting Up Permissions in Adobe Admin Console

Step 1: Navigate to API Credentials

1. Log in to Adobe Admin Console
2. Navigate to Products → Customer Journey Analytics
3. Click on API Credentials
4. Select your OAuth Server-to-Server credential (Client ID)

Step 2: Add Product Profile

1. Click Add Product Profile
2. Select a profile that includes CJA Reporting API Access
3. Ensure the profile has the following permissions:
   • Reporting API: Full access to POST /reports and GET /reports/topItems
   • Workspace API: Access to filters, calculated metrics, projects
   • Data Views: Read access to configured data views

Step 3: Verify OAuth Scopes

In the API credential configuration, verify these scopes are enabled:

• openid
• AdobeID
• read_organizations
• additional_info.projectedProductContext
• cja.reporting ← CRITICAL
• cja.workspace ← CRITICAL

Step 4: Generate New Credentials (if needed)

If updating an existing credential doesn't enable reporting access:

1. Create a new OAuth Server-to-Server credential
2. Add CJA API as a service
3. Select a Product Profile with full Reporting API access
4. Copy the new Client ID and Client Secret to your .env file

Example Queries and Expected Results

Session Analysis

Query:

Show me session count in a bar chart for the last 30 days

What Happens:

1. Claude identifies you want session metrics over time
2. Calls cja_get_trended_report or cja_run_report with:
   • Metric: sessions or visits
   • Date range: Last 30 days
   • Granularity: day
3. Formats results as a text-based bar chart or table
4. Returns daily session counts with visualization

Expected Output:

Session Count - Last 30 Days

Oct 1  ████████████████ 1,245
Oct 2  ██████████████ 1,108
Oct 3  ███████████████ 1,189
...
Oct 30 ████████████████████ 1,523

Total Sessions: 38,420
Average: 1,281 sessions/day
Peak: Oct 30 (1,523 sessions)

Top Pages Analysis

Query:

What are the top 10 pages by page views this month?

What Happens:

1. Calls cja_get_top_items with:
   • Dimension: page or pageName
   • Metric: pageviews
   • Date range: This month
   • Limit: 10
2. Returns ranked list of pages

Expected Output:

Top 10 Pages by Page Views - October 2025

1. /home                    15,234 views
2. /products                 8,901 views
3. /about                    6,543 views
4. /contact                  4,321 views
5. /blog/article-123         3,987 views
6. /pricing                  3,456 views
7. /features                 2,890 views
8. /blog                     2,543 views
9. /documentation            2,234 views
10. /support                 1,987 views

Total: 52,096 page views

Conversion Funnel

Query:

Show me the checkout funnel conversion rates for last week

What Happens:

1. Calls cja_get_funnel_analysis with predefined checkout steps
2. Or calls cja_run_report multiple times for each funnel step
3. Calculates drop-off rates between steps

Expected Output:

Checkout Funnel - Last 7 Days

Step 1: Product Page     → 10,000 visitors (100.0%)
         ↓ 45.0%
Step 2: Add to Cart      →  4,500 visitors ( 45.0%)
         ↓ 66.7%
Step 3: Checkout Started →  3,000 visitors ( 30.0%)
         ↓ 50.0%
Step 4: Payment Info     →  1,500 visitors ( 15.0%)
         ↓ 80.0%
Step 5: Purchase         →  1,200 visitors ( 12.0%)

Overall Conversion Rate: 12.0%
Biggest Drop-off: Product Page → Add to Cart (55%)

Marketing Attribution

Query:

Show me first-touch attribution for conversions in the last 14 days

What Happens:

1. Calls cja_get_attribution_analysis with:
   • Attribution model: first_touch
   • Success event: orders or conversions
   • Date range: Last 14 days
2. Returns marketing channel credit distribution

Expected Output:

First-Touch Attribution - Last 14 Days
Total Conversions: 450

Channel              Conversions    % of Total    Revenue
──────────────────────────────────────────────────────────
Organic Search            180         40.0%      $45,000
Paid Search               135         30.0%      $33,750
Direct                     68         15.1%      $17,000
Email                      45         10.0%      $11,250
Social Media               22          4.9%       $5,500

Top First-Touch Channel: Organic Search
Highest Revenue/Conversion: Paid Search ($250 avg)

Available MCP Tools

Core Reporting

• cja_run_report - Run custom analytics reports
• cja_get_top_items - Get top-performing items for a dimension
• cja_get_trended_report - Get time-series trends
• cja_get_breakdown_report - Get multi-dimensional breakdowns

Metadata

• cja_list_dimensions - List available dimensions
• cja_list_metrics - List available metrics
• cja_list_calculated_metrics - List calculated metrics
• cja_list_filters - List filters/segments
• cja_list_date_ranges - List predefined date ranges
• cja_get_dataview_info - Get data view configuration

Advanced Analytics

• cja_search_dimension_items - Search for dimension values
• cja_get_sessions_data - Analyze session metrics
• cja_get_conversions_data - Analyze conversion events
• cja_get_attribution_analysis - Run attribution models
• cja_get_funnel_analysis - Analyze conversion funnels

License

MIT License - see LICENSE file for details

Support

For issues or questions:

• Adobe CJA API Documentation: https://developer.adobe.com/cja-apis/docs/
• Adobe Developer Console: https://developer.adobe.com/console
• Model Context Protocol: https://modelcontextprotocol.io/