add_to_timeline
Place a media clip from the project panel into a specific sequence timeline at a defined track, time, and insertion mode using this automation tool for Adobe Premiere Pro.
Instructions
Adds a media clip from the project panel to a sequence timeline at a specific track and time.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| insertMode | No | Whether to overwrite existing content or insert and shift | |
| projectItemId | Yes | The ID of the project item (clip) to add | |
| sequenceId | Yes | The ID of the sequence (timeline) to add the clip to | |
| time | Yes | The time in seconds where the clip should be placed on the timeline | |
| trackIndex | Yes | The index of the video or audio track (0-based) |
Implementation Reference
- src/tools/index.ts:1001-1024 (handler)The primary handler for the 'add_to_timeline' MCP tool. Validates arguments (via outer executeTool), calls the bridge, and formats success/error responses.private async addToTimeline(sequenceId: string, projectItemId: string, trackIndex: number, time: number, insertMode = 'overwrite'): Promise<any> { try { const result = await this.bridge.addToTimeline(sequenceId, projectItemId, trackIndex, time); return { success: true, message: `Clip added to timeline successfully`, sequenceId: sequenceId, projectItemId: projectItemId, trackIndex: trackIndex, time: time, insertMode: insertMode, ...result }; } catch (error) { return { success: false, error: `Failed to add clip to timeline: ${error instanceof Error ? error.message : String(error)}`, sequenceId: sequenceId, projectItemId: projectItemId, trackIndex: trackIndex, time: time }; } }
- src/tools/index.ts:143-153 (schema)Input schema and metadata definition for the add_to_timeline tool, used for validation and MCP tool discovery.{ name: 'add_to_timeline', description: 'Adds a media clip from the project panel to a sequence timeline at a specific track and time.', inputSchema: z.object({ sequenceId: z.string().describe('The ID of the sequence (timeline) to add the clip to'), projectItemId: z.string().describe('The ID of the project item (clip) to add'), trackIndex: z.number().describe('The index of the video or audio track (0-based)'), time: z.number().describe('The time in seconds where the clip should be placed on the timeline'), insertMode: z.enum(['overwrite', 'insert']).optional().describe('Whether to overwrite existing content or insert and shift') }) },
- src/tools/index.ts:462-464 (registration)Switch case in executeTool() that registers and routes calls to the add_to_timeline handler.case 'add_to_timeline': return await this.addToTimeline(args.sequenceId, args.projectItemId, args.trackIndex, args.time, args.insertMode); case 'remove_from_timeline':
- src/bridge/index.ts:268-289 (helper)Supporting bridge method invoked by the tool handler. Executes ExtendScript in Premiere Pro to insert the project item as a clip on the specified track at the given time.async addToTimeline(sequenceId: string, projectItemId: string, trackIndex: number, time: number): Promise<PremiereProClip> { const script = ` // Add item to timeline var sequence = app.project.getSequenceByID("${sequenceId}"); var projectItem = app.project.getProjectItemByID("${projectItemId}"); var track = sequence.videoTracks[${trackIndex}]; var clip = track.insertClip(projectItem, ${time}); // Return clip info JSON.stringify({ id: clip.clipID, name: clip.name, inPoint: clip.start, outPoint: clip.end, duration: clip.duration, mediaPath: clip.projectItem.getMediaPath() }); `; return await this.executeScript(script); }
- src/index.ts:74-81 (registration)MCP server registration: ListTools handler that exposes add_to_timeline (via PremiereProTools.getAvailableTools()) to MCP clients.this.server.setRequestHandler(ListToolsRequestSchema, async () => { const tools = this.tools.getAvailableTools().map((tool) => ({ name: tool.name, description: tool.description, inputSchema: zodToJsonSchema(tool.inputSchema, { $refStrategy: 'none' }) })); return { tools }; });