Basecamp MCP Server

Instructions

Implementation Reference

• src/lib/basecamp-client.ts:266-279 (handler)

  Core handler function that executes the Basecamp API POST request to create a new card step (sub-task).
  async createCardStep( projectId: string, cardId: string, title: string, dueOn?: string, assigneeIds?: string[] ): Promise<CardStep> { const data: any = { title }; if (dueOn) data.due_on = dueOn; if (assigneeIds) data.assignee_ids = assigneeIds; const response = await this.client.post(`/buckets/${projectId}/card_tables/cards/${cardId}/steps.json`, data); return response.data; }
• src/index.ts:724-742 (handler)

  MCP server tool handler switch case that receives tool call parameters and delegates to BasecampClient.createCardStep, then formats the response.
  case 'create_card_step': { const step = await client.createCardStep( typedArgs.project_id, typedArgs.card_id, typedArgs.title, typedArgs.due_on, typedArgs.assignee_ids ); return { content: [{ type: 'text', text: JSON.stringify({ status: 'success', step, message: `Step '${typedArgs.title}' created successfully` }, null, 2) }] }; }
• src/index.ts:352-366 (schema)

  Tool schema definition including inputSchema for validation and the tool name registration in the listTools response.
  { name: 'create_card_step', description: 'Create a new step (sub-task) for a card', inputSchema: { type: 'object', properties: { project_id: { type: 'string', description: 'The project ID' }, card_id: { type: 'string', description: 'The card ID' }, title: { type: 'string', description: 'The step title' }, due_on: { type: 'string', description: 'Optional due date (ISO 8601 format)' }, assignee_ids: { type: 'array', items: { type: 'string' }, description: 'Array of person IDs to assign to the step' }, }, required: ['project_id', 'card_id', 'title'], }, },
• src/index.ts:104-540 (registration)

  The listTools request handler where all tools including 'create_card_step' are registered and returned to MCP clients.
  this.server.setRequestHandler(ListToolsRequestSchema, async () => { return { tools: [ // Core tools { name: 'get_projects', description: 'Get all Basecamp projects', inputSchema: { type: 'object', properties: {}, }, }, { name: 'get_project', description: 'Get details for a specific project', inputSchema: { type: 'object', properties: { project_id: { type: 'string', description: 'The project ID' }, }, required: ['project_id'], }, }, { name: 'search_basecamp', description: 'Search across Basecamp projects, todos, and messages', inputSchema: { type: 'object', properties: { query: { type: 'string', description: 'Search query' }, project_id: { type: 'string', description: 'Optional project ID to limit search scope' }, }, required: ['query'], }, }, { name: 'global_search', description: 'Search projects, todos and campfire messages across all projects', inputSchema: { type: 'object', properties: { query: { type: 'string', description: 'Search query' }, }, required: ['query'], }, }, // Todo tools { name: 'get_todolists', description: 'Get todo lists for a project', inputSchema: { type: 'object', properties: { project_id: { type: 'string', description: 'The project ID' }, }, required: ['project_id'], }, }, { name: 'get_todos', description: 'Get todos from a todo list', inputSchema: { type: 'object', properties: { project_id: { type: 'string', description: 'Project ID' }, todolist_id: { type: 'string', description: 'The todo list ID' }, }, required: ['project_id', 'todolist_id'], }, }, // Card Table tools { name: 'get_card_table', description: 'Get the card table details for a project', inputSchema: { type: 'object', properties: { project_id: { type: 'string', description: 'The project ID' }, }, required: ['project_id'], }, }, { name: 'get_columns', description: 'Get all columns in a card table', inputSchema: { type: 'object', properties: { project_id: { type: 'string', description: 'The project ID' }, card_table_id: { type: 'string', description: 'The card table ID' }, }, required: ['project_id', 'card_table_id'], }, }, { name: 'get_cards', description: 'Get all cards in a column', inputSchema: { type: 'object', properties: { project_id: { type: 'string', description: 'The project ID' }, column_id: { type: 'string', description: 'The column ID' }, }, required: ['project_id', 'column_id'], }, }, { name: 'create_card', description: 'Create a new card in a column', inputSchema: { type: 'object', properties: { project_id: { type: 'string', description: 'The project ID' }, column_id: { type: 'string', description: 'The column ID' }, title: { type: 'string', description: 'The card title' }, content: { type: 'string', description: 'Optional card content/description' }, due_on: { type: 'string', description: 'Optional due date (ISO 8601 format)' }, notify: { type: 'boolean', description: 'Whether to notify assignees (default: false)' }, }, required: ['project_id', 'column_id', 'title'], }, }, // Column Management tools { name: 'create_column', description: 'Create a new column in a card table', inputSchema: { type: 'object', properties: { project_id: { type: 'string', description: 'The project ID' }, card_table_id: { type: 'string', description: 'The card table ID' }, title: { type: 'string', description: 'The column title' }, }, required: ['project_id', 'card_table_id', 'title'], }, }, { name: 'update_column', description: 'Update a column title', inputSchema: { type: 'object', properties: { project_id: { type: 'string', description: 'The project ID' }, column_id: { type: 'string', description: 'The column ID' }, title: { type: 'string', description: 'The new column title' }, }, required: ['project_id', 'column_id', 'title'], }, }, { name: 'move_column', description: 'Move a column to a new position', inputSchema: { type: 'object', properties: { project_id: { type: 'string', description: 'The project ID' }, card_table_id: { type: 'string', description: 'The card table ID' }, column_id: { type: 'string', description: 'The column ID' }, position: { type: 'number', description: 'The new 1-based position' }, }, required: ['project_id', 'card_table_id', 'column_id', 'position'], }, }, { name: 'update_column_color', description: 'Update a column color', inputSchema: { type: 'object', properties: { project_id: { type: 'string', description: 'The project ID' }, column_id: { type: 'string', description: 'The column ID' }, color: { type: 'string', description: 'The hex color code (e.g., #FF0000)' }, }, required: ['project_id', 'column_id', 'color'], }, }, // Card Management tools { name: 'get_card', description: 'Get details for a specific card', inputSchema: { type: 'object', properties: { project_id: { type: 'string', description: 'The project ID' }, card_id: { type: 'string', description: 'The card ID' }, }, required: ['project_id', 'card_id'], }, }, { name: 'update_card', description: 'Update a card', inputSchema: { type: 'object', properties: { project_id: { type: 'string', description: 'The project ID' }, card_id: { type: 'string', description: 'The card ID' }, title: { type: 'string', description: 'The new card title' }, content: { type: 'string', description: 'The new card content/description' }, due_on: { type: 'string', description: 'Due date (ISO 8601 format)' }, assignee_ids: { type: 'array', items: { type: 'string' }, description: 'Array of person IDs to assign to the card' }, }, required: ['project_id', 'card_id'], }, }, { name: 'move_card', description: 'Move a card to a new column', inputSchema: { type: 'object', properties: { project_id: { type: 'string', description: 'The project ID' }, card_id: { type: 'string', description: 'The card ID' }, column_id: { type: 'string', description: 'The destination column ID' }, }, required: ['project_id', 'card_id', 'column_id'], }, }, { name: 'complete_card', description: 'Mark a card as complete', inputSchema: { type: 'object', properties: { project_id: { type: 'string', description: 'The project ID' }, card_id: { type: 'string', description: 'The card ID' }, }, required: ['project_id', 'card_id'], }, }, // Card Steps tools { name: 'get_card_steps', description: 'Get all steps (sub-tasks) for a card', inputSchema: { type: 'object', properties: { project_id: { type: 'string', description: 'The project ID' }, card_id: { type: 'string', description: 'The card ID' }, }, required: ['project_id', 'card_id'], }, }, { name: 'create_card_step', description: 'Create a new step (sub-task) for a card', inputSchema: { type: 'object', properties: { project_id: { type: 'string', description: 'The project ID' }, card_id: { type: 'string', description: 'The card ID' }, title: { type: 'string', description: 'The step title' }, due_on: { type: 'string', description: 'Optional due date (ISO 8601 format)' }, assignee_ids: { type: 'array', items: { type: 'string' }, description: 'Array of person IDs to assign to the step' }, }, required: ['project_id', 'card_id', 'title'], }, }, { name: 'complete_card_step', description: 'Mark a card step as complete', inputSchema: { type: 'object', properties: { project_id: { type: 'string', description: 'The project ID' }, step_id: { type: 'string', description: 'The step ID' }, }, required: ['project_id', 'step_id'], }, }, // Communication tools { name: 'get_campfire_lines', description: 'Get recent messages from a Basecamp campfire (chat room)', inputSchema: { type: 'object', properties: { project_id: { type: 'string', description: 'The project ID' }, campfire_id: { type: 'string', description: 'The campfire/chat room ID' }, }, required: ['project_id', 'campfire_id'], }, }, { name: 'get_comments', description: 'Get comments for a Basecamp item', inputSchema: { type: 'object', properties: { recording_id: { type: 'string', description: 'The item ID' }, project_id: { type: 'string', description: 'The project ID' }, }, required: ['recording_id', 'project_id'], }, }, // Document tools { name: 'get_documents', description: 'List documents in a vault', inputSchema: { type: 'object', properties: { project_id: { type: 'string', description: 'Project ID' }, vault_id: { type: 'string', description: 'Vault ID' }, }, required: ['project_id', 'vault_id'], }, }, { name: 'create_document', description: 'Create a document in a vault', inputSchema: { type: 'object', properties: { project_id: { type: 'string', description: 'Project ID' }, vault_id: { type: 'string', description: 'Vault ID' }, title: { type: 'string', description: 'Document title' }, content: { type: 'string', description: 'Document HTML content' }, }, required: ['project_id', 'vault_id', 'title', 'content'], }, }, { name: 'update_document', description: 'Update a document', inputSchema: { type: 'object', properties: { project_id: { type: 'string', description: 'Project ID' }, document_id: { type: 'string', description: 'Document ID' }, title: { type: 'string', description: 'New title' }, content: { type: 'string', description: 'New HTML content' }, }, required: ['project_id', 'document_id'], }, }, { name: 'trash_document', description: 'Move a document to trash', inputSchema: { type: 'object', properties: { project_id: { type: 'string', description: 'Project ID' }, document_id: { type: 'string', description: 'Document ID' }, }, required: ['project_id', 'document_id'], }, }, // File tools { name: 'get_uploads', description: 'List uploads in a project or vault', inputSchema: { type: 'object', properties: { project_id: { type: 'string', description: 'Project ID' }, vault_id: { type: 'string', description: 'Optional vault ID to limit to specific vault' }, }, required: ['project_id'], }, }, // Webhook tools { name: 'get_webhooks', description: 'List webhooks for a project', inputSchema: { type: 'object', properties: { project_id: { type: 'string', description: 'Project ID' }, }, required: ['project_id'], }, }, { name: 'create_webhook', description: 'Create a webhook', inputSchema: { type: 'object', properties: { project_id: { type: 'string', description: 'Project ID' }, payload_url: { type: 'string', description: 'Payload URL' }, types: { type: 'array', items: { type: 'string' }, description: 'Event types' }, }, required: ['project_id', 'payload_url'], }, }, { name: 'delete_webhook', description: 'Delete a webhook', inputSchema: { type: 'object', properties: { project_id: { type: 'string', description: 'Project ID' }, webhook_id: { type: 'string', description: 'Webhook ID' }, }, required: ['project_id', 'webhook_id'], }, }, // Check-in tools { name: 'get_daily_check_ins', description: "Get project's daily checking questionnaire", inputSchema: { type: 'object', properties: { project_id: { type: 'string', description: 'The project ID' }, page: { type: 'number', description: 'Page number for paginated response' }, }, required: ['project_id'], }, }, { name: 'get_question_answers', description: 'Get answers on daily check-in question', inputSchema: { type: 'object', properties: { project_id: { type: 'string', description: 'The project ID' }, question_id: { type: 'string', description: 'The question ID' }, page: { type: 'number', description: 'Page number for paginated response' }, }, required: ['project_id', 'question_id'], }, }, ], }; });