YouTube MCP Server

Instructions

Implementation Reference

• src/services/video.ts:62-79 (handler)

  Core handler function in VideoService that fetches video details from YouTube API v3, structures the response with a URL, and handles errors.

  async getVideo({
    videoId,
    parts = ['snippet', 'contentDetails', 'statistics']
  }: VideoParams): Promise<unknown> {
    try {
      this.initialize();
  
      const response = await this.youtube.videos.list({
        part: parts,
        id: [videoId]
      });
  
      const videoData = response.data.items?.[0] || null;
      return this.createStructuredVideo(videoData);
    } catch (error) {
      throw new Error(`Failed to get video: ${error instanceof Error ? error.message : String(error)}`);
    }
  }

• src/server-utils.ts:132-152 (registration)

  Registers the 'videos_getVideo' tool with MCP server, including input schema using Zod and a thin wrapper handler that delegates to VideoService.

  server.registerTool(
      'videos_getVideo',
      {
          title: 'Get Video Details',
          description: 'Get detailed information about a YouTube video including URL',
          annotations: { readOnlyHint: true, idempotentHint: true },
          inputSchema: {
              videoId: z.string().describe('The YouTube video ID'),
              parts: z.array(z.string()).optional().describe('Parts of the video to retrieve'),
          },
      },
      async ({ videoId, parts }) => {
          const result = await videoService.getVideo({ videoId, parts });
          return {
              content: [{
                  type: 'text',
                  text: JSON.stringify(result, null, 2)
              }]
          };
      }
  );

• src/types.ts:4-7 (schema)

  TypeScript interface defining input parameters for getVideo method (videoId required, parts optional).

  export interface VideoParams {
    videoId: string;
    parts?: string[];
  }

• src/services/video.ts:18-31 (helper)

  Helper method that structures video data by adding a canonical URL and ensuring videoId is top-level.

  private createStructuredVideo(videoData: unknown): unknown {
    if (!videoData) return null;
  
    // eslint-disable-next-line @typescript-eslint/no-explicit-any
    const v = videoData as any;
    const videoId = v.id || v.id?.videoId;
    const url = videoId ? `https://www.youtube.com/watch?v=${videoId}` : null;
  
    return {
      ...v,
      url,
      videoId
    };
  }