create_card
Add a new task to a Focalboard project board by specifying its title, properties, description, and column placement.
Instructions
Create a new card (task) in a board. You can set the title, properties, description, and column placement.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| boardId | Yes | The ID of the board to create the card in | |
| title | Yes | The title/name of the card | |
| properties | No | Property values for the card (e.g., {"Status": "To Do", "Priority": "High"}). Use property names, not IDs. | |
| description | No | Optional description/content for the card in markdown format |
Implementation Reference
- src/index.ts:313-354 (handler)The primary handler for executing the 'create_card' MCP tool. Validates inputs, creates a basic card, optionally applies properties and description, then returns the resulting card JSON.case 'create_card': { const boardId = args?.boardId as string; const title = args?.title as string; const properties = (args?.properties as Record<string, string>) || {}; const description = args?.description as string | undefined; if (!boardId || !title) { throw new Error('boardId and title are required'); } // Create the card first const cardData: any = { title, fields: { properties: {}, contentOrder: [] } }; let card = await focalboard.createCard(boardId, cardData); // If properties are provided, update the card with them if (Object.keys(properties).length > 0) { card = await focalboard.updateCardProperties(card.id, boardId, properties); } // If description is provided, add it as a text block if (description) { await focalboard.createTextBlock(boardId, card.id, description); // Refresh card to get updated contentOrder card = await focalboard.getCard(card.id); } return { content: [ { type: 'text', text: JSON.stringify(card, null, 2) } ] }; }
- src/index.ts:79-107 (registration)Registration of the 'create_card' tool in the MCP tools list, including description and input schema definition.{ name: 'create_card', description: 'Create a new card (task) in a board. You can set the title, properties, description, and column placement.', inputSchema: { type: 'object', properties: { boardId: { type: 'string', description: 'The ID of the board to create the card in' }, title: { type: 'string', description: 'The title/name of the card' }, properties: { type: 'object', description: 'Property values for the card (e.g., {"Status": "To Do", "Priority": "High"}). Use property names, not IDs.', additionalProperties: { type: 'string' } }, description: { type: 'string', description: 'Optional description/content for the card in markdown format' } }, required: ['boardId', 'title'] } },
- src/index.ts:82-105 (schema)JSON schema defining the input parameters for the 'create_card' tool.inputSchema: { type: 'object', properties: { boardId: { type: 'string', description: 'The ID of the board to create the card in' }, title: { type: 'string', description: 'The title/name of the card' }, properties: { type: 'object', description: 'Property values for the card (e.g., {"Status": "To Do", "Priority": "High"}). Use property names, not IDs.', additionalProperties: { type: 'string' } }, description: { type: 'string', description: 'Optional description/content for the card in markdown format' } }, required: ['boardId', 'title']
- src/focalboard-client.ts:221-251 (helper)Helper method in FocalboardClient that implements the core card creation logic by making a POST request to the Focalboard API endpoint `/boards/{boardId}/blocks`.async createCard(boardId: string, card: Partial<Card>): Promise<Card> { const newCard = { boardId, parentId: card.parentId || boardId, type: 'card', schema: 1, title: card.title || '', fields: card.fields || { properties: {}, contentOrder: [], icon: '', isTemplate: false }, createAt: Date.now(), updateAt: Date.now(), deleteAt: 0, createdBy: '', modifiedBy: '', limited: false }; // The /blocks endpoint expects an array and returns an array const createdCards = await this.makeRequest<Card[]>( `/boards/${boardId}/blocks`, 'POST', [newCard] ); // Return the first (and only) created card return createdCards[0]; }