Focalboard MCP Server

Instructions

Implementation Reference

• src/index.ts:292-307 (handler)

  MCP tool handler for 'search_boards': validates input parameters (teamId optional, searchTerm required), calls focalboard.searchBoards, and formats response as JSON text content.

  case 'search_boards': {
    const teamId = (args?.teamId as string) || '0';
    const searchTerm = args?.searchTerm as string;
    if (!searchTerm) {
      throw new Error('searchTerm is required');
    }
    const boards = await focalboard.searchBoards(teamId, searchTerm);
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(boards, null, 2)
        }
      ]
    };
  }

• src/index.ts:60-78 (registration)

  Registration of the 'search_boards' tool in the MCP tools array, defining name, description, and input schema for validation.

  {
    name: 'search_boards',
    description: 'Search for boards by name or keyword within a team.',
    inputSchema: {
      type: 'object',
      properties: {
        teamId: {
          type: 'string',
          description: 'The team ID to search within (default: "0" for default team)',
          default: '0'
        },
        searchTerm: {
          type: 'string',
          description: 'The search term to find boards'
        }
      },
      required: ['searchTerm']
    }
  },

• src/focalboard-client.ts:165-172 (helper)

  Helper method in FocalboardClient that performs the actual API search request for boards using the makeRequest utility with query param 'q'.

  async searchBoards(teamId: string, term: string): Promise<Board[]> {
    return this.makeRequest<Board[]>(
      `/teams/${teamId}/boards/search`,
      'GET',
      undefined,
      { q: term }
    );
  }

• src/index.ts:63-77 (schema)

  JSON schema definition for 'search_boards' tool input validation, specifying teamId (optional) and required searchTerm.

  inputSchema: {
    type: 'object',
    properties: {
      teamId: {
        type: 'string',
        description: 'The team ID to search within (default: "0" for default team)',
        default: '0'
      },
      searchTerm: {
        type: 'string',
        description: 'The search term to find boards'
      }
    },
    required: ['searchTerm']
  }