Focalboard MCP Server

Instructions

Implementation Reference

• src/index.ts:356-374 (handler)

  The MCP tool handler for 'get_cards'. Extracts boardId, page, and perPage from input arguments, calls the focalboard client's getCards method, and returns the list of cards as formatted JSON text content.

  case 'get_cards': {
    const boardId = args?.boardId as string;
    const page = (args?.page as number) || 0;
    const perPage = (args?.perPage as number) || 100;
  
    if (!boardId) {
      throw new Error('boardId is required');
    }
  
    const cards = await focalboard.getCards(boardId, page, perPage);
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(cards, null, 2)
        }
      ]
    };
  }

• src/index.ts:111-130 (schema)

  JSON schema defining the input parameters for the 'get_cards' tool: boardId (required), page and perPage (optional with defaults).

  inputSchema: {
    type: 'object',
    properties: {
      boardId: {
        type: 'string',
        description: 'The ID of the board to list cards from'
      },
      page: {
        type: 'number',
        description: 'Page number for pagination (default: 0)',
        default: 0
      },
      perPage: {
        type: 'number',
        description: 'Number of cards per page (default: 100)',
        default: 100
      }
    },
    required: ['boardId']
  }

• src/index.ts:108-131 (registration)

  Registration of the 'get_cards' tool in the tools array, including name, description, and input schema. This array is used by the ListToolsRequestHandler.

  {
    name: 'get_cards',
    description: 'List all cards (tasks) in a board with pagination support.',
    inputSchema: {
      type: 'object',
      properties: {
        boardId: {
          type: 'string',
          description: 'The ID of the board to list cards from'
        },
        page: {
          type: 'number',
          description: 'Page number for pagination (default: 0)',
          default: 0
        },
        perPage: {
          type: 'number',
          description: 'Number of cards per page (default: 100)',
          default: 100
        }
      },
      required: ['boardId']
    }
  },

• src/focalboard-client.ts:202-209 (helper)

  Helper method in FocalboardClient that performs the actual API request to retrieve cards from a board with pagination, called by the tool handler.

  async getCards(boardId: string, page: number = 0, perPage: number = 100): Promise<Card[]> {
    return this.makeRequest<Card[]>(
      `/boards/${boardId}/cards`,
      'GET',
      undefined,
      { page: page.toString(), per_page: perPage.toString() }
    );
  }