dogfrogfog/youtube-analytics-mcp

YouTube Analytics MCP Server

A Model Context Protocol (MCP) server for YouTube Analytics data access with demographics and discovery tools, built with a scalable config-driven architecture.

Core Features

• Channel Analytics: Get comprehensive channel overview, growth patterns, and vital signs
• Video Performance: Analyze individual video metrics, audience retention, and drop-off points
• Viewer Demographics: Access age/gender breakdowns and geographic distribution data
• Discovery Insights: Understand traffic sources and search terms driving views
• Engagement Metrics: Track likes, comments, shares, and viewer interaction patterns
• Audience Retention: Identify exact moments where viewers drop off for content optimization
• Performance Comparison: Compare metrics between different time periods
• Public Channel Analysis: Research competitor channels and trending content

Core Architecture Principles

This MCP server follows a config-driven architecture that provides:

• Maintainability: Clear separation between tool definitions and implementation
• Scalability: Easy to add new tools without modifying core server logic
• Consistency: Standardized error handling and response formatting
• Readability: Clean, declarative configuration that serves as documentation

Setup

1. Google API Credentials

To use this YouTube Analytics MCP server, you need to set up Google API credentials:

1. Go to the Google Cloud Console
2. Create a new project or select an existing one
3. Enable the YouTube Analytics API and YouTube Data API v3
4. Go to "Credentials" and create a new OAuth 2.0 Client ID
5. Download the credentials as JSON
6. Save the file as credentials.json in the src/auth/ directory

Privacy Note: All data processing happens locally on your computer. Your credentials and analytics data never leave your machine - the server runs entirely locally and connects directly to Google's APIs from your system.

2. Development

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode
npm run dev

# Inspect with MCP Inspector
npm run inspect

Architecture Overview

Project Structure

src/
├── index.ts                 # Main server entry point (config-driven)
├── tool-configs.ts         # Central tool configuration aggregator
├── types.ts                # TypeScript interfaces and types
├── auth/
│   ├── tool-configs.ts     # Authentication tool configurations
│   └── ...
├── server/
│   ├── info-configs.ts     # Server info tool configurations
│   └── ...
└── youtube/tools/
    ├── channel-configs.ts  # Channel analysis tool configurations
    ├── health-configs.ts   # Channel health tool configurations
    ├── audience-configs.ts # Audience demographics tool configurations
    ├── discovery-configs.ts # Traffic source tool configurations
    ├── performance-configs.ts # Performance analysis tool configurations
    └── engagement-configs.ts # Engagement metrics tool configurations

Tool Configuration Structure

Each tool is defined by a configuration object:

interface ToolConfig<T = any> {
  name: string;           // Tool name
  description: string;    // Tool description
  schema: any;           // Zod schema for validation
  handler: (params: T, context: ToolContext) => Promise<ToolResult>;
  category?: string;      // Optional grouping
}

Available Tools

Authentication Tools

• check_auth_status - Check YouTube authentication status
• revoke_auth - Revoke authentication and clear tokens

Channel Tools

• get_channel_info - Get basic channel information
• get_channel_videos - Get list of channel videos with filters

Health Tools

• get_channel_overview - Get channel vital signs and growth patterns
• get_comparison_metrics - Compare metrics between time periods
• get_average_view_percentage - Get average view percentage

Audience Tools

• get_video_demographics - Get age/gender breakdown
• get_geographic_distribution - Get viewer geographic distribution
• get_subscriber_analytics - Get subscriber vs non-subscriber analytics

Discovery Tools

• get_traffic_sources - Get traffic source analysis
• get_search_terms - Get search terms for SEO insights

Performance Tools

• get_audience_retention - Track viewer retention patterns
• get_retention_dropoff_points - Find exact drop-off moments

Engagement Tools

• get_engagement_metrics - Analyze likes, comments, and shares

Adding New Tools

To add a new tool, simply create a configuration object and add it to the appropriate config file:

// In src/youtube/tools/new-category-configs.ts
export const newCategoryToolConfigs: ToolConfig[] = [
  {
    name: "new_tool_name",
    description: "Description of what the tool does",
    category: "new_category",
    schema: z.object({
      // Define your parameters here
      param1: z.string().describe("Description of parameter 1"),
      param2: z.number().optional().describe("Optional parameter 2"),
    }),
    handler: async ({ param1, param2 }, { getYouTubeClient }: ToolContext) => {
      try {
        const youtubeClient = await getYouTubeClient();
        // Your tool implementation here
        
        return {
          content: [{
            type: "text",
            text: "Tool result here"
          }]
        };
      } catch (error) {
        return {
          content: [{
            type: "text",
            text: `Error: ${error instanceof Error ? error.message : String(error)}`
          }],
          isError: true
        };
      }
    },
  },
];

// Then add to src/tool-configs.ts
export const allToolConfigs = [
  // ... existing configs
  ...newCategoryToolConfigs,
];

Benefits of Config-Driven Architecture

1. Clean Separation: Tool definitions are separate from server setup
2. Type Safety: Full TypeScript support for schemas and handlers
3. Documentation: Config serves as living documentation
4. Testing: Easier to unit test individual tools
5. Extensibility: Simple to add new tool categories
6. Maintainability: Consistent patterns across all tools
7. Scalability: Easy to manage many tools without cluttering main file

Server Registration Pattern

The server automatically registers all tools from configuration:

// Automatic registration from configs - no manual server.tool() calls needed
allToolConfigs.forEach((toolConfig) => {
  server.tool(
    toolConfig.name,           // Tool name from config
    toolConfig.description,    // Description from config
    toolConfig.schema,         // Zod schema from config  
    async (params: any) => {   // Handler wrapper
      return toolConfig.handler(params, { 
        authManager, 
        getYouTubeClient, 
        clearYouTubeClientCache 
      });
    }
  );
});

Error Handling

All tools follow a consistent error handling pattern:

try {
  // Tool implementation
  return {
    content: [{ type: "text", text: "Success result" }]
  };
} catch (error) {
  return {
    content: [{ 
      type: "text", 
      text: `Error: ${error instanceof Error ? error.message : String(error)}` 
    }],
    isError: true
  };
}

Context Injection

Tools receive a context object with shared dependencies:

interface ToolContext {
  authManager: AuthManager;
  getYouTubeClient: () => Promise<YouTubeClient>;
  clearYouTubeClientCache: () => void;
}

This architecture makes the codebase more maintainable, scalable, and easier to extend while preserving all existing functionality.