Motion MCP Server

Instructions

Implementation Reference

• src/handlers/CustomFieldHandler.ts:7-135 (handler)

  Main handler class implementing the motion_custom_fields tool. Supports 7 operations: list, create, delete, add_to_project, remove_from_project, add_to_task, remove_from_task. Each operation has a dedicated private method with validation and error handling.
  export class CustomFieldHandler extends BaseHandler { async handle(args: MotionCustomFieldsArgs): Promise<McpToolResponse> { try { const { operation } = args; switch(operation) { case 'list': return await this.handleList(args); case 'create': return await this.handleCreate(args); case 'delete': return await this.handleDelete(args); case 'add_to_project': return await this.handleAddToProject(args); case 'remove_from_project': return await this.handleRemoveFromProject(args); case 'add_to_task': return await this.handleAddToTask(args); case 'remove_from_task': return await this.handleRemoveFromTask(args); default: return this.handleUnknownOperation(operation); } } catch (error: unknown) { return this.handleError(error); } } private async handleList(args: MotionCustomFieldsArgs): Promise<McpToolResponse> { if (!args.workspaceId && !args.workspaceName) { return this.handleError(new Error('Workspace ID or workspace name is required for list operation')); } const workspace = await this.workspaceResolver.resolveWorkspace({ workspaceId: args.workspaceId, workspaceName: args.workspaceName }); const fields = await this.motionService.getCustomFields(workspace.id); return formatCustomFieldList(fields); } private async handleCreate(args: MotionCustomFieldsArgs): Promise<McpToolResponse> { if ((!args.workspaceId && !args.workspaceName) || !args.name || !args.field) { return this.handleError(new Error('Workspace ID/name, name, and field are required for create operation')); } if (args.name.length > LIMITS.CUSTOM_FIELD_NAME_MAX_LENGTH) { return this.handleError(new Error(`Field name exceeds ${LIMITS.CUSTOM_FIELD_NAME_MAX_LENGTH} characters`)); } const isSelectType = ['select', 'multiSelect'].includes(args.field); if (!isSelectType && args.options) { return this.handleError(new Error('Options parameter is only allowed for select/multiSelect field types')); } if (isSelectType && !args.options) { return this.handleError(new Error('Options parameter is required for select/multiSelect field types')); } const workspace = await this.workspaceResolver.resolveWorkspace({ workspaceId: args.workspaceId, workspaceName: args.workspaceName }); const fieldData: CreateCustomFieldData = { name: args.name, field: args.field, ...(args.required !== undefined && { required: args.required }), ...(args.options && { metadata: { options: args.options } }) }; const newField = await this.motionService.createCustomField(workspace.id, fieldData); return formatCustomFieldDetail(newField); } private async handleDelete(args: MotionCustomFieldsArgs): Promise<McpToolResponse> { if ((!args.workspaceId && !args.workspaceName) || !args.fieldId) { return this.handleError(new Error('Workspace ID/name and field ID are required for delete operation')); } const workspace = await this.workspaceResolver.resolveWorkspace({ workspaceId: args.workspaceId, workspaceName: args.workspaceName }); await this.motionService.deleteCustomField(workspace.id, args.fieldId); return formatCustomFieldSuccess('deleted'); } private async handleAddToProject(args: MotionCustomFieldsArgs): Promise<McpToolResponse> { if (!args.projectId || !args.fieldId) { return this.handleError(new Error('Project ID and field ID are required for add_to_project operation')); } if (args.value !== undefined && args.value !== null && !args.field) { return this.handleError(new Error('Field type (field) is required when providing a value. Use "text", "number", "multiSelect", etc.')); } const result = await this.motionService.addCustomFieldToProject(args.projectId, args.fieldId, args.value, args.field); return formatCustomFieldSuccess('added', 'project', args.projectId, result); } private async handleRemoveFromProject(args: MotionCustomFieldsArgs): Promise<McpToolResponse> { if (!args.projectId || !args.valueId) { return this.handleError(new Error('Project ID and valueId (custom field value ID) are required for remove_from_project operation')); } await this.motionService.removeCustomFieldFromProject(args.projectId, args.valueId); return formatCustomFieldSuccess('removed', 'project', args.projectId); } private async handleAddToTask(args: MotionCustomFieldsArgs): Promise<McpToolResponse> { if (!args.taskId || !args.fieldId) { return this.handleError(new Error('Task ID and field ID are required for add_to_task operation')); } if (args.value !== undefined && args.value !== null && !args.field) { return this.handleError(new Error('Field type (field) is required when providing a value. Use "text", "number", "multiSelect", etc.')); } const result = await this.motionService.addCustomFieldToTask(args.taskId, args.fieldId, args.value, args.field); return formatCustomFieldSuccess('added', 'task', args.taskId, result); } private async handleRemoveFromTask(args: MotionCustomFieldsArgs): Promise<McpToolResponse> { if (!args.taskId || !args.valueId) { return this.handleError(new Error('Task ID and valueId (custom field value ID) are required for remove_from_task operation')); } await this.motionService.removeCustomFieldFromTask(args.taskId, args.valueId); return formatCustomFieldSuccess('removed', 'task', args.taskId); } }
• src/tools/ToolDefinitions.ts:289-355 (registration)

  Tool definition for motion_custom_fields with name, description, and complete input schema including all 7 operations (list, create, delete, add_to_project, remove_from_project, add_to_task, remove_to_task) and their required/optional parameters.
  export const customFieldsToolDefinition: McpToolDefinition = { name: TOOL_NAMES.CUSTOM_FIELDS, description: "Manage custom fields for tasks and projects. Required params per operation: list: workspaceId or workspaceName. create: workspaceId/workspaceName + name + field (type); options[] also required for select/multiSelect. delete: workspaceId/workspaceName + fieldId. add_to_project: projectId + fieldId. remove_from_project: projectId + valueId. add_to_task: taskId + fieldId. remove_from_task: taskId + valueId.", inputSchema: { type: "object", properties: { operation: { type: "string", enum: ["list", "create", "delete", "add_to_project", "remove_from_project", "add_to_task", "remove_from_task"], description: "Operation to perform" }, fieldId: { type: "string", description: "Custom field definition ID. Required for: delete, add_to_project, add_to_task. For remove operations, use valueId instead." }, valueId: { type: "string", description: "Custom field value assignment ID (not the field definition ID). Required for: remove_from_project, remove_from_task." }, workspaceId: { type: "string", description: "Workspace ID. Required for: list, create, delete." }, workspaceName: { type: "string", description: "Workspace name (alternative to workspaceId). Required for: list, create, delete." }, name: { type: "string", description: "Field name. Required for: create." }, field: { type: "string", enum: ["text", "url", "date", "person", "multiPerson", "phone", "select", "multiSelect", "number", "email", "checkbox", "relatedTo"], description: "Field type. Required for: create. Also needed for add_to_project/add_to_task when providing a non-null value." }, options: { type: "array", items: { type: "string" }, description: "Option labels. Required for: create when field is select or multiSelect." }, required: { type: "boolean", description: "Whether field is required on tasks/projects." }, projectId: { type: "string", description: "Project ID. Required for: add_to_project, remove_from_project." }, taskId: { type: "string", description: "Task ID. Required for: add_to_task, remove_from_task." }, value: { oneOf: [ { type: "string" }, { type: "number" }, { type: "boolean" }, { type: "array", items: { type: "string" } }, { type: "null" } ], description: "Field value to set. Optional for add_to_project/add_to_task. When provided and non-null, the field param (type) is also required." } }, required: ["operation"] } };
• src/types/mcp-tool-args.ts:80-95 (schema)

  TypeScript interface defining MotionCustomFieldsArgs with all possible parameters for the 7 operations, including operation type, fieldId, valueId, workspaceId/workspaceName, name, field type, options, required flag, projectId, taskId, and value.
  export type CustomFieldsOperation = 'list' | 'create' | 'delete' | 'add_to_project' | 'remove_from_project' | 'add_to_task' | 'remove_from_task'; export interface MotionCustomFieldsArgs { operation: CustomFieldsOperation; fieldId?: string; valueId?: string; workspaceId?: string; workspaceName?: string; name?: string; field?: 'text' | 'url' | 'date' | 'person' | 'multiPerson' | 'phone' | 'select' | 'multiSelect' | 'number' | 'email' | 'checkbox' | 'relatedTo'; options?: string[]; required?: boolean; projectId?: string; taskId?: string; value?: string | number | boolean | string[] | null; }
• src/handlers/HandlerFactory.ts:27-38 (registration)

  Handler factory registration mapping the TOOL_NAMES.CUSTOM_FIELDS constant to the CustomFieldHandler class, enabling dynamic handler instantiation based on tool name.
  private registerHandlers(): void { this.handlers.set(TOOL_NAMES.TASKS, TaskHandler); this.handlers.set(TOOL_NAMES.PROJECTS, ProjectHandler); this.handlers.set(TOOL_NAMES.WORKSPACES, WorkspaceHandler); this.handlers.set(TOOL_NAMES.USERS, UserHandler); this.handlers.set(TOOL_NAMES.SEARCH, SearchHandler); this.handlers.set(TOOL_NAMES.COMMENTS, CommentHandler); this.handlers.set(TOOL_NAMES.CUSTOM_FIELDS, CustomFieldHandler); this.handlers.set(TOOL_NAMES.RECURRING_TASKS, RecurringTaskHandler); this.handlers.set(TOOL_NAMES.SCHEDULES, ScheduleHandler); this.handlers.set(TOOL_NAMES.STATUSES, StatusHandler); }
• src/utils/responseFormatters.ts:340-393 (helper)

  Helper functions for formatting custom field responses: formatCustomFieldList for listing multiple fields, formatCustomFieldDetail for single field details, and formatCustomFieldSuccess for operation success messages with valueId tracking.
  export function formatCustomFieldList(fields: MotionCustomField[]): CallToolResult { if (fields.length === 0) { return formatMcpSuccess("No custom fields found."); } const fieldFormatter = (field: MotionCustomField) => { const name = field.name ? `${field.name} ` : ''; return `- ${name}ID: ${field.id} [Type: ${field.field}]`; }; return formatListResponse(fields, `Found ${fields.length} custom field${fields.length === 1 ? '' : 's'}`, fieldFormatter); } /** * Format single custom field response */ export function formatCustomFieldDetail(field: MotionCustomField): CallToolResult { const details = [ `Custom field created successfully:`, field.name ? `- Name: ${field.name}` : null, `- ID: ${field.id}`, `- Type: ${field.field}` ].filter(Boolean).join('\n'); return formatMcpSuccess(details); } /** * Format success message for custom field operations */ export function formatCustomFieldSuccess(operation: string, entityType?: string, entityId?: string, apiResponse?: MotionCustomFieldValue): CallToolResult { let message = `Custom field ${operation} successfully`; if (entityType && entityId) { message += ` for ${entityType} ${entityId}`; } // For add operations, include the API response so users can obtain the valueId for later removal if (apiResponse) { if (apiResponse.id) { message += `\nValue ID: ${apiResponse.id}`; if (entityType) { message += `\nTip: Use this valueId with remove_from_${entityType} to remove this custom field assignment.`; } } else { message += `\nNote: The API did not return a valueId. To find the valueId, use motion_tasks (operation: get) or inspect the task/project's customFieldValues.`; } if (apiResponse.type) { message += `\nType: ${apiResponse.type}`; } if (apiResponse.value !== undefined) { message += `\nValue: ${JSON.stringify(apiResponse.value)}`; } } return formatMcpSuccess(message); }