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'] } },