Monday.com MCP Server

Instructions

Implementation Reference

• src/mcp_server_monday/item.py:12-64 (handler)

  Core implementation of the tool logic: constructs a GraphQL query to fetch items from specified groups in a board, executes it via monday_client, and returns formatted text content.

  async def handle_monday_list_items_in_groups(
      boardId: str,
      groupIds: list[str],
      limit: int,
      monday_client: MondayClient,
      cursor: Optional[str] = None,
  ) -> list[types.TextContent]:
      """List all items in the specified groups of a Monday.com board"""
  
      if groupIds and not cursor:
          formatted_group_ids = ", ".join([f'"{group_id}"' for group_id in groupIds])
          items_page_params = f"""
              query_params: {{
                  rules: [
                      {{column_id: "group", compare_value: [{formatted_group_ids}], operator: any_of}}
                  ]
              }}
          """
      else:
          items_page_params = f'cursor: "{cursor}"'
  
      items_page_params += f" limit: {limit}"
      query = f"""
      query {{
          boards (ids: {boardId}) {{
              items_page ({items_page_params}) {{
                  cursor
                  items {{
                      id
                      name
                      updates {{
                          id
                          body
                      }}
                      column_values {{
                          id
                          text
                          value
                      }}
                  }}
              }}
          }}
      }}
      """
  
      response = monday_client.custom._query(query)
      return [
          types.TextContent(
              type="text",
              text=f"Items in groups {groupIds} of Monday.com board {boardId}: {json.dumps(response)}",
          )
      ]

• src/mcp_server_monday/fastmcp_server.py:203-223 (registration)

  MCP tool registration using @mcp.tool() decorator. This wrapper function defines the tool interface, fetches the Monday client, calls the core handler, and handles errors.

  @mcp.tool()
  async def monday_list_items_in_groups(
      boardId: str, groupIds: List[str], limit: int, cursor: Optional[str] = None
  ) -> str:
      """List all items in the specified groups of a Monday.com board.
  
      Args:
          boardId: Monday.com Board ID that the Item or Sub-item is on.
          groupIds: List of group IDs to list items from.
          limit: Maximum number of items to return.
          cursor: Pagination cursor for continuing from previous results.
      """
      try:
          client = get_monday_client()
          result = await handle_monday_list_items_in_groups(
              boardId, groupIds, limit, cursor, client
          )
          return result[0].text
      except Exception as e:
          return f"Error listing items in groups: {e}"