Monday.com MCP Server

Instructions

Implementation Reference

• src/mcp_server_monday/item.py:102-149 (handler)

  Core implementation of the monday-create-item tool logic. Creates an item or subitem on a Monday.com board using the MondayClient API, constructs the item URL, and returns formatted text content.

  async def handle_monday_create_item(
      boardId: str,
      itemTitle: str,
      monday_client: MondayClient,
      groupId: Optional[str] = None,
      parentItemId: Optional[str] = None,
      columnValues: Optional[dict] = None,
  ) -> list[types.TextContent]:
      """Create a new item in a Monday.com Board. Optionally, specify the parent Item ID to create a Sub-item."""
      if parentItemId is None and groupId is not None:
          response = monday_client.items.create_item(
              board_id=boardId,
              group_id=groupId,
              item_name=itemTitle,
              column_values=columnValues,
          )
      elif parentItemId is not None and groupId is None:
          response = monday_client.items.create_subitem(
              parent_item_id=parentItemId,
              subitem_name=itemTitle,
              column_values=columnValues,
          )
      else:
          return [
              types.TextContent(
                  type="text",
                  text="You can set either groupId or parentItemId argument, but not both.",
              )
          ]
  
      try:
          data = response["data"]
          id_key = "create_item" if parentItemId is None else "create_subitem"
          item_url = f"{MONDAY_WORKSPACE_URL}/boards/{boardId}/pulses/{data.get(id_key).get('id')}"
          return [
              types.TextContent(
                  type="text",
                  text=f"Created a new Monday.com item. URL: {item_url}",
              )
          ]
      except Exception as e:
          return [
              types.TextContent(
                  type="text",
                  text=f"Error creating Monday.com item: {e}",
              )
          ]

• src/mcp_server_monday/fastmcp_server.py:126-151 (registration)

  Tool registration for 'monday_create_item' (maps to 'monday-create-item') using FastMCP. Thin wrapper around the core handler, defines input parameters and docstring schema.

  @mcp.tool()
  async def monday_create_item(
      boardId: str,
      itemTitle: str,
      groupId: Optional[str] = None,
      parentItemId: Optional[str] = None,
      columnValues: Optional[Dict[str, Any]] = None,
  ) -> str:
      """Create a new item in a Monday.com Board. Optionally, specify the parent Item ID to create a Sub-item.
  
      Args:
          boardId: Monday.com Board ID that the Item or Sub-item is on.
          itemTitle: Name of the Monday.com Item or Sub-item that will be created.
          groupId: Monday.com Board's Group ID to create the Item in. If set, parentItemId should not be set.
          parentItemId: Monday.com Item ID to create the Sub-item under. If set, groupId should not be set.
          columnValues: Dictionary of column values to set {column_id: value}.
      """
      try:
          client = get_monday_client()
          result = await handle_monday_create_item(
              boardId, itemTitle, groupId, parentItemId, columnValues, client
          )
          return result[0].text
      except Exception as e:
          return f"Error creating item: {e}"

• src/mcp_server_monday/constants.py:8-8 (helper)

  Constant used in the handler to construct the URL of the created item.

  MONDAY_WORKSPACE_URL = f"https://{MONDAY_WORKSPACE_NAME}.monday.com"

• src/mcp_server_monday/fastmcp_server.py:39-44 (helper)

  Helper function to initialize and retrieve the MondayClient instance using the API key.

  def get_monday_client() -> MondayClient:
      global monday_client
      if monday_client is None:
          monday_client = MondayClient(MONDAY_API_KEY)
      return monday_client

• src/mcp_server_monday/fastmcp_server.py:19-30 (registration)

  Import of the handle_monday_create_item handler function into the server module for use in tool wrappers.

  from mcp_server_monday.item import (
      handle_monday_archive_item,
      handle_monday_create_item,
      handle_monday_create_update_on_item,
      handle_monday_delete_item,
      handle_monday_get_item_by_id,
      handle_monday_get_item_updates,
      handle_monday_list_items_in_groups,
      handle_monday_list_subitems_in_items,
      handle_monday_move_item_to_group,
      handle_monday_update_item,
  )