Focalboard MCP Server

Instructions

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];
  }