Twitter MCP Server

Instructions

Implementation Reference

• src/handlers/directmessage.handlers.ts:252-283 (handler)

  The main handler function that executes the createMediaMessage tool. It sends a direct message with media using Twitter API v1.sendDm, handles errors like missing client, user/media not found, size limits, and unsupported types.

  export const handleCreateMediaMessage: TwitterHandler<CreateMediaMessageArgs> = async (
      client: TwitterClient | null,
      { recipientId, text, mediaId, altText }: CreateMediaMessageArgs
  ): Promise<HandlerResponse> => {
      if (!client) {
          return createMissingTwitterApiKeyResponse('createMediaMessage');
      }
      try {
          // Using v1 API for sending DMs with media
          const dmParams: any = {
              recipient_id: recipientId,
              text,
              media_id: mediaId
          };
  
          const result = await client.v1.sendDm(dmParams);
  
          return createResponse(`Direct message with media sent successfully to user ${recipientId}. Response: ${JSON.stringify(result, null, 2)}`);
      } catch (error) {
          if (error instanceof Error) {
              if (error.message.includes('404')) {
                  throw new Error(`Failed to send media message: User ${recipientId} not found or media ${mediaId} not found.`);
              } else if (error.message.includes('413')) {
                  throw new Error(`Failed to send media message: Media file too large. Check Twitter's media size limits.`);
              } else if (error.message.includes('415')) {
                  throw new Error(`Failed to send media message: Unsupported media type. Check Twitter's supported media formats.`);
              }
              throw new Error(formatTwitterError(error, 'sending media message'));
          }
          throw error;
      }
  }; 

• src/types/handlers.ts:106-112 (schema)

  TypeScript interface defining the input parameters for the createMediaMessage handler.

  export interface CreateMediaMessageArgs {
      recipientId: string;
      text: string;
      mediaId: string;
      mediaType?: string;
      altText?: string;
  }

• src/tools.ts:582-611 (schema)

  Input schema definition for the createMediaMessage tool used for MCP validation.

  createMediaMessage: {
      description: 'Send a direct message with media attachments',
      inputSchema: {
          type: 'object',
          properties: {
              recipientId: { 
                  type: 'string', 
                  description: 'The ID of the user to send the message to' 
              },
              text: { 
                  type: 'string', 
                  description: 'The text content of the direct message' 
              },
              mediaId: { 
                  type: 'string', 
                  description: 'The media ID of the uploaded media to attach' 
              },
              mediaType: { 
                  type: 'string', 
                  enum: ['image/jpeg', 'image/png', 'image/gif', 'video/mp4'],
                  description: 'MIME type of the media file' 
              },
              altText: { 
                  type: 'string', 
                  description: 'Alternative text for the media (accessibility)' 
              }
          },
          required: ['recipientId', 'text', 'mediaId']
      }
  },

• src/index.ts:376-385 (registration)

  Tool registration in the MCP server's CallToolRequestSchema handler switch statement, dispatching to the specific handler function.

  case 'createMediaMessage': {
      const { recipientId, text, mediaId, mediaType, altText } = request.params.arguments as {
          recipientId: string;
          text: string;
          mediaId: string;
          mediaType?: string;
          altText?: string;
      };
      response = await handleCreateMediaMessage(client, { recipientId, text, mediaId, mediaType, altText });
      break;

• src/tools.ts:582-611 (registration)

  Tool definition and registration in the TOOLS object used by the MCP server for listing and validating tools.

  createMediaMessage: {
      description: 'Send a direct message with media attachments',
      inputSchema: {
          type: 'object',
          properties: {
              recipientId: { 
                  type: 'string', 
                  description: 'The ID of the user to send the message to' 
              },
              text: { 
                  type: 'string', 
                  description: 'The text content of the direct message' 
              },
              mediaId: { 
                  type: 'string', 
                  description: 'The media ID of the uploaded media to attach' 
              },
              mediaType: { 
                  type: 'string', 
                  enum: ['image/jpeg', 'image/png', 'image/gif', 'video/mp4'],
                  description: 'MIME type of the media file' 
              },
              altText: { 
                  type: 'string', 
                  description: 'Alternative text for the media (accessibility)' 
              }
          },
          required: ['recipientId', 'text', 'mediaId']
      }
  },